diff --git a/imports.md b/imports.md
index 7555963..497f48d 100644
--- a/imports.md
+++ b/imports.md
@@ -2,19 +2,21 @@
-
+
Types
@@ -28,6 +30,7 @@ combined with a couple of errors that are always possible:
access-denied
not-supported
out-of-memory
+concurrency-conflict
See each individual API for what the POSIX equivalents are. They sometimes differ per API.
Enum Cases
@@ -47,6 +50,11 @@ combined with a couple of errors that are always possible:
POSIX equivalent: EOPNOTSUPP
+invalid-argument
+One of the arguments is invalid.
+
POSIX equivalent: EINVAL
+
+
out-of-memory
Not enough memory to complete the operation.
POSIX equivalent: ENOMEM, ENOBUFS, EAI_MEMORY
@@ -58,6 +66,7 @@ combined with a couple of errors that are always possible:
concurrency-conflict
This operation is incompatible with another asynchronous operation that is already in progress.
+
POSIX equivalent: EALREADY
not-in-progress
@@ -72,74 +81,26 @@ combined with a couple of errors that are always possible:
Note: this is scheduled to be removed when futures are natively supported.
-address-family-not-supported
-The specified address-family is not supported.
-
-
-address-family-mismatch
-An IPv4 address was passed to an IPv6 resource, or vice versa.
-
-
-invalid-remote-address
-The socket address is not a valid remote address. E.g. the IP address is set to INADDR_ANY, or the port is set to 0.
-
-
-ipv4-only-operation
-The operation is only supported on IPv4 resources.
-
-
-ipv6-only-operation
-The operation is only supported on IPv6 resources.
+
invalid-state
+The operation is not valid in the socket's current state.
new-socket-limit
A new socket resource could not be created because of a system limit.
-already-attached
-The socket is already attached to another network.
-
-
-already-bound
-The socket is already bound.
-
-
-already-connected
-The socket is already in the Connection state.
-
-
-not-bound
-The socket is not bound to any local address.
-
-
-not-connected
-The socket is not in the Connection state.
-
-
address-not-bindable
A bind operation failed because the provided address is not an address that the `network` can bind to.
address-in-use
-A bind operation failed because the provided address is already in use.
-
-
-ephemeral-ports-exhausted
-A bind operation failed because there are no ephemeral ports available.
+
A bind operation failed because the provided address is already in use or because there are no ephemeral ports available.
remote-unreachable
The remote address is not reachable
-already-listening
-The socket is already in the Listener state.
-
-
-not-listening
-The socket is already in the Listener state.
-
-
connection-refused
The connection was forcefully rejected
@@ -148,11 +109,11 @@ combined with a couple of errors that are always possible:
The connection was reset.
-datagram-too-large
+connection-aborted
+A connection was aborted.
-invalid-name
-The provided name is a syntactically invalid domain name.
+
datagram-too-large
name-unresolvable
@@ -225,7 +186,7 @@ combined with a couple of errors that are always possible:
ipv4: ipv4-socket-address
ipv6: ipv6-socket-address
-
+
This interface provides a value-export of the default network handle..
Types
@@ -240,7 +201,7 @@ combined with a couple of errors that are always possible:
-
+
A poll API intended to let users wait for I/O events on multiple handles
at once.
@@ -290,7 +251,7 @@ being reaedy for I/O.
-
+
Types
@@ -308,31 +269,60 @@ being reaedy for I/O.
#### `type ip-address-family`
[`ip-address-family`](#ip_address_family)
-#### `record datagram`
+#### `record incoming-datagram`
+
A received datagram.
+Record Fields
+
+-
+
data: list<u8>
+The payload.
+
Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes.
+
+-
+
remote-address: ip-socket-address
+The source address.
+
This field is guaranteed to match the remote address the stream was initialized with, if any.
+Equivalent to the src_addr out parameter of recvfrom.
+
+
+
+A datagram to be sent out.
Record Fields
-data: list<u8>remote-address: ip-socket-address-
+
data: list<u8>
+The payload.
+
+-
+
remote-address: option<ip-socket-address>
+The destination address.
+
The requirements on this field depend on how the stream was initialized:
+
+- with a remote address: this field must be None or match the stream's remote address exactly.
+- without a remote address: this field is required.
+
+If this value is None, the send operation is equivalent to send in POSIX. Otherwise it is equivalent to sendto.
+
+
+
Functions
Bind the socket to a specific network on the provided IP address and port.
If the IP address is zero (0.0.0.0 in IPv4, :: in IPv6), it is left to the implementation to decide which
network interface(s) to bind to.
-If the TCP/UDP port is zero, the socket will be bound to a random free port.
-When a socket is not explicitly bound, the first invocation to connect will implicitly bind the socket.
+If the port is zero, the socket will be bound to a random free port.
Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
Typical start errors
-address-family-mismatch: The local-address has the wrong address family. (EINVAL)already-bound: The socket is already bound. (EINVAL)concurrency-conflict: Another bind or connect operation is already in progress. (EALREADY)invalid-argument: The local-address has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)invalid-state: The socket is already bound. (EINVAL)
Typical finish errors
-ephemeral-ports-exhausted: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)address-in-use: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)address-in-use: Address is already in use. (EADDRINUSE)address-not-bindable: local-address is not an address that the network can bind to. (EADDRNOTAVAIL)not-in-progress: A bind operation is not in progress.Set the destination address.
-The local-address is updated based on the best network path to remote-address.
-When a destination address is set:
-
-- all receive operations will only return datagrams sent from the provided
remote-address.
-- the
send function can only be used to send to this destination.
-
-Note that this function does not generate any network traffic and the peer is not aware of this "connection".
-Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
-Typical start errors
+
+Set up inbound & outbound communication channels, optionally to a specific peer.
+This function only changes the local socket configuration and does not generate any network traffic.
+On success, the remote-address of the socket is updated. The local-address may be updated as well,
+based on the best network path to remote-address.
+When a remote-address is provided, the returned streams are limited to communicating with that specific peer:
+
+send can only be used to send to this destination.receive will only return datagrams sent from the provided remote-address.
+This method may be called multiple times on the same socket to change its association, but
+only the most recently returned pair of streams will be operational. Implementations may trap if
+the streams returned by a previous invocation haven't been dropped yet before calling stream again.
+The POSIX equivalent in pseudo-code is:
+
if (was previously connected) {
+ connect(s, AF_UNSPEC)
+}
+if (remote_address is Some) {
+ connect(s, remote_address)
+}
+
+Unlike in POSIX, the socket must already be explicitly bound.
+Typical errors
-address-family-mismatch: The remote-address has the wrong address family. (EAFNOSUPPORT)invalid-remote-address: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)invalid-remote-address: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)already-attached: The socket is already bound to a different network. The network passed to connect must be identical to the one passed to bind.concurrency-conflict: Another bind or connect operation is already in progress. (EALREADY)
-Typical finish errors
-
-ephemeral-ports-exhausted: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)not-in-progress: A connect operation is not in progress.would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)invalid-argument: remote-address is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)invalid-argument: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)invalid-state: The socket is not bound.address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)connection-refused: The connection was refused. (ECONNREFUSED)
References
@@ -397,100 +396,24 @@ If the TCP/UDP port is zero, the socket will be bound to a random free port.
Params
-Return values
-
-
-Params
-
-Return values
-
-
-Receive messages on the socket.
-This function attempts to receive up to max-results datagrams on the socket without blocking.
-The returned list may contain fewer elements than requested, but never more.
-If max-results is 0, this function returns successfully with an empty list.
-Typical errors
-
-not-bound: The socket is not bound to any local address. (EINVAL)remote-unreachable: The remote address is not reachable. (ECONNREFUSED, ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN)would-block: There is no pending data available to be read at the moment. (EWOULDBLOCK, EAGAIN)
-References
-
-Params
-
-Return values
-
-
-Send messages on the socket.
-This function attempts to send all provided datagrams on the socket without blocking and
-returns how many messages were actually sent (or queued for sending).
-This function semantically behaves the same as iterating the datagrams list and sequentially
-sending each individual datagram until either the end of the list has been reached or the first error occurred.
-If at least one datagram has been sent successfully, this function never returns an error.
-If the input list is empty, the function returns ok(0).
-The remote address option is required. To send a message to the "connected" peer,
-call remote-address to get their address.
-Typical errors
-
-address-family-mismatch: The remote-address has the wrong address family. (EAFNOSUPPORT)invalid-remote-address: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)invalid-remote-address: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)already-connected: The socket is in "connected" mode and the datagram.remote-address does not match the address passed to connect. (EISCONN)not-bound: The socket is not bound to any local address. Unlike POSIX, this function does not perform an implicit bind.remote-unreachable: The remote address is not reachable. (ECONNREFUSED, ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN)datagram-too-large: The datagram is too large. (EMSGSIZE)would-block: The send buffer is currently full. (EWOULDBLOCK, EAGAIN)
-References
-
-Params
-
Return values
Get the current bound address.
+POSIX mentions:
+
+If the socket has not been bound to a local name, the value
+stored in the object pointed to by address is unspecified.
+
+WASI is stricter and requires local-address to return invalid-state when the socket hasn't been bound yet.
Typical errors
-not-bound: The socket is not bound to any local address.invalid-state: The socket is not bound to any local address.
References
-Get the address set with connect.
+Get the address the socket is currently streaming to.
Typical errors
-not-connected: The socket is not connected to a remote address. (ENOTCONN)invalid-state: The socket is not streaming to a specific remote address. (ENOTCONN)
References
@@ -544,10 +467,9 @@ call remote-address to get their address.
Equivalent to the IPV6_V6ONLY socket option.
Typical errors
-ipv6-only-operation: (get/set) this socket is an IPv4 socket.already-bound: (set) The socket is already bound.not-supported: (get/set) this socket is an IPv4 socket.invalid-state: (set) The socket is already bound.not-supported: (set) Host does not support dual-stack sockets. (Implementations are not required to.)concurrency-conflict: (set) Another bind or connect operation is already in progress. (EALREADY)
Params
@@ -569,9 +491,10 @@ call remote-address to get their address.
Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+If the provided value is 0, an invalid-argument error is returned.
Typical errors
-concurrency-conflict: (set) Another bind or connect operation is already in progress. (EALREADY)invalid-argument: (set) The TTL value must be 1 or higher.
Params
@@ -593,15 +516,13 @@ call remote-address to get their address.
The kernel buffer space reserved for sends/receives on this socket.
-Note #1: an implementation may choose to cap or round the buffer size when setting the value.
-In other words, after setting a value, reading the same setting back may return a different value.
-Note #2: there is not necessarily a direct relationship between the kernel buffer size and the bytes of
-actual data to be sent/received by the application, because the kernel might also use the buffer space
-for internal metadata structures.
+If the provided value is 0, an invalid-argument error is returned.
+Any other value will never cause an error, but it might be silently clamped and/or rounded.
+I.e. after setting a value, reading the same setting back may return a different value.
Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
Typical errors
-concurrency-conflict: (set) Another bind or connect operation is already in progress. (EALREADY)invalid-argument: (set) The provided value was 0.
Params
@@ -652,7 +573,126 @@ It's planned to be removed when future is natively supported in Pre
-
+
+Receive messages on the socket.
+This function attempts to receive up to max-results datagrams on the socket without blocking.
+The returned list may contain fewer elements than requested, but never more.
+This function returns successfully with an empty list when either:
+
+max-results is 0, or:max-results is greater than 0, but no results are immediately available.
+This function never returns error(would-block).
+Typical errors
+
+remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)connection-refused: The connection was refused. (ECONNREFUSED)
+References
+
+Params
+
+Return values
+
+
+Create a pollable which will resolve once the stream is ready to receive again.
+Note: this function is here for WASI Preview2 only.
+It's planned to be removed when future is natively supported in Preview3.
+Params
+
+Return values
+
+
+Check readiness for sending. This function never blocks.
+Returns the number of datagrams permitted for the next call to send,
+or an error. Calling send with more datagrams than this function has
+permitted will trap.
+When this function returns ok(0), the subscribe pollable will
+become ready when this function will report at least ok(1), or an
+error.
+Never returns would-block.
+Params
+
+Return values
+
+
+Send messages on the socket.
+This function attempts to send all provided datagrams on the socket without blocking and
+returns how many messages were actually sent (or queued for sending). This function never
+returns error(would-block). If none of the datagrams were able to be sent, ok(0) is returned.
+This function semantically behaves the same as iterating the datagrams list and sequentially
+sending each individual datagram until either the end of the list has been reached or the first error occurred.
+If at least one datagram has been sent successfully, this function never returns an error.
+If the input list is empty, the function returns ok(0).
+Each call to send must be permitted by a preceding check-send. Implementations must trap if
+either check-send was not called or datagrams contains more items than check-send permitted.
+Typical errors
+
+invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)invalid-argument: remote-address is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)invalid-argument: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)invalid-argument: The socket is in "connected" mode and remote-address is some value that does not match the address passed to stream. (EISCONN)invalid-argument: The socket is not "connected" and no value for remote-address was provided. (EDESTADDRREQ)remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)connection-refused: The connection was refused. (ECONNREFUSED)datagram-too-large: The datagram is too large. (EMSGSIZE)
+References
+
+Params
+
+Return values
+
+
+Create a pollable which will resolve once the stream is ready to send again.
+Note: this function is here for WASI Preview2 only.
+It's planned to be removed when future is natively supported in Preview3.
+Params
+
+Return values
+
+
Types
@@ -673,14 +713,13 @@ It's planned to be removed when future is natively supported in Pre
Create a new UDP socket.
Similar to socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP) in POSIX.
This function does not require a network capability handle. This is considered to be safe because
-at time of creation, the socket is not bound to any network yet. Up to the moment bind/connect is called,
+at time of creation, the socket is not bound to any network yet. Up to the moment bind is called,
the socket is effectively an in-memory configuration object, unable to communicate with the outside world.
All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.
Typical errors
-not-supported: The host does not support UDP sockets. (EOPNOTSUPP)address-family-not-supported: The specified address-family is not supported. (EAFNOSUPPORT)new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)not-supported: The specified address-family is not supported. (EAFNOSUPPORT)new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
References:
@@ -697,18 +736,41 @@ the socket is effectively an in-memory configuration object, unable to communica
-
+
+
+Types
+
+
+Functions
+
+Returns a string that is suitable to assist humans in debugging
+this error.
+WARNING: The returned string should not be consumed mechanically!
+It may change across platforms, hosts, or other implementation
+details. Parsing this string is a major platform-compatibility
+hazard.
+Params
+
+Return values
+
+
WASI I/O is an I/O abstraction API which is currently focused on providing
stream types.
In the future, the component model is expected to add built-in stream types;
when it does, they are expected to subsume this API.
Types
-
-pollable
+
+error
-#### `resource error`
-
+#### `type pollable`
+[`pollable`](#pollable)
+
+#### `variant stream-error`
An error for input-stream and output-stream operations.
Variant Cases
@@ -728,20 +790,6 @@ future operations.
Functions
-
-Returns a string that's suitable to assist humans in debugging this
-error.
-The returned string will change across platforms and hosts which
-means that parsing it, for example, would be a
-platform-compatibility hazard.
-Params
-
-Return values
-
Perform a non-blocking read from the stream.
This function returns a list of bytes containing the read data,
@@ -1012,7 +1060,68 @@ is ready for reading, before performing the splice.
-
+
+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.
+
+Types
+
+pollable
+
+#### `type instant`
+`u64`
+
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.
+
+u64
+A duration of time, in nanoseconds.
+
+Functions
+
+Read the current value of the clock.
+The clock is monotonic, therefore calling this function repeatedly will
+produce a sequence of non-decreasing values.
+Return values
+
+
+Query the resolution of the clock. Returns the duration of time
+corresponding to a clock tick.
+Return values
+
+
+Create a pollable which will resolve once the specified instant
+occured.
+Params
+
+Return values
+
+
+Create a pollable which will resolve once the given duration has
+elapsed, starting at the time at which this function was called.
+occured.
+Params
+
+Return values
+
+
Types
@@ -1024,6 +1133,9 @@ is ready for reading, before performing the splice.
#### `type pollable`
[`pollable`](#pollable)
+#### `type duration`
+[`duration`](#duration)
+
#### `type network`
[`network`](#network)
@@ -1065,13 +1177,14 @@ implicitly bind the socket.
Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
Typical start errors
-address-family-mismatch: The local-address has the wrong address family. (EINVAL)already-bound: The socket is already bound. (EINVAL)concurrency-conflict: Another bind, connect or listen operation is already in progress. (EALREADY)invalid-argument: The local-address has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)invalid-argument: local-address is not a unicast address. (EINVAL)invalid-argument: local-address is an IPv4-mapped IPv6 address, but the socket has ipv6-only enabled. (EINVAL)invalid-state: The socket is already bound. (EINVAL)
Typical finish errors
-ephemeral-ports-exhausted: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)address-in-use: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)address-in-use: Address is already in use. (EADDRINUSE)address-not-bindable: local-address is not an address that the network can bind to. (EADDRNOTAVAIL)not-in-progress: A bind operation is not in progress.- the socket is transitioned into the Connection state
- a pair of streams is returned that can be used to read & write to the connection
+POSIX mentions:
+
+If connect() fails, the state of the socket is unspecified. Conforming applications should
+close the file descriptor and create a new socket before attempting to reconnect.
+
+WASI prescribes the following behavior:
+
+- If
connect fails because an input/state validation error, the socket should remain usable.
+- If a connection was actually attempted but failed, the socket should become unusable for further network communication.
+Besides
drop, any method after such a failure may return an error.
+
Typical start errors
-address-family-mismatch: The remote-address has the wrong address family. (EAFNOSUPPORT)invalid-remote-address: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EADDRNOTAVAIL on Windows)invalid-remote-address: The port in remote-address is set to 0. (EADDRNOTAVAIL on Windows)already-attached: The socket is already attached to a different network. The network passed to connect must be identical to the one passed to bind.already-connected: The socket is already in the Connection state. (EISCONN)already-listening: The socket is already in the Listener state. (EOPNOTSUPP, EINVAL on Windows)concurrency-conflict: Another bind, connect or listen operation is already in progress. (EALREADY)invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)invalid-argument: remote-address is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)invalid-argument: remote-address is an IPv4-mapped IPv6 address, but the socket has ipv6-only enabled. (EINVAL, EADDRNOTAVAIL on Illumos)invalid-argument: remote-address is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EADDRNOTAVAIL on Windows)invalid-argument: The port in remote-address is set to 0. (EADDRNOTAVAIL on Windows)invalid-argument: The socket is already attached to a different network. The network passed to connect must be identical to the one passed to bind.invalid-state: The socket is already in the Connection state. (EISCONN)invalid-state: The socket is already in the Listener state. (EOPNOTSUPP, EINVAL on Windows)
Typical finish errors
timeout: Connection timed out. (ETIMEDOUT)connection-refused: The connection was forcefully rejected. (ECONNREFUSED)connection-reset: The connection was reset. (ECONNRESET)remote-unreachable: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN)ephemeral-ports-exhausted: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)connection-aborted: The connection was aborted. (ECONNABORTED)remote-unreachable: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)not-in-progress: A connect operation is not in progress.would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
@@ -1166,14 +1293,13 @@ implicitly bind the socket.
Typical start errors
-not-bound: The socket is not bound to any local address. (EDESTADDRREQ)already-connected: The socket is already in the Connection state. (EISCONN, EINVAL on BSD)already-listening: The socket is already in the Listener state.concurrency-conflict: Another bind, connect or listen operation is already in progress. (EINVAL on BSD)invalid-state: The socket is not bound to any local address. (EDESTADDRREQ)invalid-state: The socket is already in the Connection state. (EISCONN, EINVAL on BSD)invalid-state: The socket is already in the Listener state.
Typical finish errors
-ephemeral-ports-exhausted: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)not-in-progress: A listen operation is not in progress.would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
@@ -1203,15 +1329,27 @@ implicitly bind the socket.
Accept a new client socket.
-The returned socket is bound and in the Connection state.
+The returned socket is bound and in the Connection state. The following properties are inherited from the listener socket:
+
+address-familyipv6-onlykeep-alive-enabledkeep-alive-idle-timekeep-alive-intervalkeep-alive-counthop-limitreceive-buffer-sizesend-buffer-size
On success, this function returns the newly accepted client socket along with
a pair of streams that can be used to read & write to the connection.
Typical errors
-not-listening: Socket is not in the Listener state. (EINVAL)would-block: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)invalid-state: Socket is not in the Listener state. (EINVAL)would-block: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)connection-aborted: An incoming connection was pending, but was terminated by the client before this listener could accept it. (ECONNABORTED)new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
-Host implementations must skip over transient errors returned by the native accept syscall.
References
Get the bound local address.
+POSIX mentions:
+
+If the socket has not been bound to a local name, the value
+stored in the object pointed to by address is unspecified.
+
+WASI is stricter and requires local-address to return invalid-state when the socket hasn't been bound yet.
Typical errors
-not-bound: The socket is not bound to any local address.invalid-state: The socket is not bound to any local address.
References
-Get the bound remote address.
+Get the remote address.
Typical errors
-not-connected: The socket is not connected to a remote address. (ENOTCONN)invalid-state: The socket is not connected to a remote address. (ENOTCONN)
References
@@ -1269,6 +1413,17 @@ a pair of streams that can be used to read & write to the connection.
+
+Whether the socket is listening for new connections.
+Equivalent to the SO_ACCEPTCONN socket option.
+Params
+
+Return values
+
Whether this is a IPv4 or IPv6 socket.
Equivalent to the SO_DOMAIN socket option.
@@ -1285,10 +1440,9 @@ a pair of streams that can be used to read & write to the connection.
Equivalent to the IPV6_V6ONLY socket option.
Typical errors
-ipv6-only-operation: (get/set) this socket is an IPv4 socket.already-bound: (set) The socket is already bound.invalid-state: (set) The socket is already bound.not-supported: (get/set) this socket is an IPv4 socket.not-supported: (set) Host does not support dual-stack sockets. (Implementations are not required to.)concurrency-conflict: (set) A bind, connect or listen operation is already in progress. (EALREADY)
Params
@@ -1310,10 +1464,13 @@ a pair of streams that can be used to read & write to the connection.
Hints the desired listen queue size. Implementations are free to ignore this.
+If the provided value is 0, an invalid-argument error is returned.
+Any other value will never cause an error, but it might be silently clamped and/or rounded.
Typical errors
-already-connected: (set) The socket is already in the Connection state.concurrency-conflict: (set) A bind, connect or listen operation is already in progress. (EALREADY)not-supported: (set) The platform does not support changing the backlog size after the initial listen.invalid-argument: (set) The provided value was 0.invalid-state: (set) The socket is already in the Connection state.
Params
@@ -1324,93 +1481,156 @@ a pair of streams that can be used to read & write to the connection.
-
+
+Enables or disables keepalive.
+The keepalive behavior can be adjusted using:
+
+keep-alive-idle-timekeep-alive-intervalkeep-alive-count
+These properties can be configured while keep-alive-enabled is false, but only come into effect when keep-alive-enabled is true.
Equivalent to the SO_KEEPALIVE socket option.
+Params
+
+Return values
+
+
+Params
+
+Return values
+
+
+Amount of time the connection has to be idle before TCP starts sending keepalive packets.
+If the provided value is 0, an invalid-argument error is returned.
+Any other value will never cause an error, but it might be silently clamped and/or rounded.
+I.e. after setting a value, reading the same setting back may return a different value.
+Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)
Typical errors
-concurrency-conflict: (set) A bind, connect or listen operation is already in progress. (EALREADY)invalid-argument: (set) The provided value was 0.
Params
Return values
-
+
Params
Return values
-
-Equivalent to the TCP_NODELAY socket option.
+
+The time between keepalive packets.
+If the provided value is 0, an invalid-argument error is returned.
+Any other value will never cause an error, but it might be silently clamped and/or rounded.
+I.e. after setting a value, reading the same setting back may return a different value.
+Equivalent to the TCP_KEEPINTVL socket option.
Typical errors
-concurrency-conflict: (set) A bind, connect or listen operation is already in progress. (EALREADY)invalid-argument: (set) The provided value was 0.
Params
Return values
-
+
Params
Return values
-
+
+The maximum amount of keepalive packets TCP should send before aborting the connection.
+If the provided value is 0, an invalid-argument error is returned.
+Any other value will never cause an error, but it might be silently clamped and/or rounded.
+I.e. after setting a value, reading the same setting back may return a different value.
+Equivalent to the TCP_KEEPCNT socket option.
+Typical errors
+
+invalid-argument: (set) The provided value was 0.
+Params
+
+Return values
+
+
+Params
+
+Return values
+
+
Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+If the provided value is 0, an invalid-argument error is returned.
Typical errors
-already-connected: (set) The socket is already in the Connection state.already-listening: (set) The socket is already in the Listener state.concurrency-conflict: (set) A bind, connect or listen operation is already in progress. (EALREADY)invalid-argument: (set) The TTL value must be 1 or higher.invalid-state: (set) The socket is already in the Connection state.invalid-state: (set) The socket is already in the Listener state.
Params
Return values
-
+
Params
Return values
The kernel buffer space reserved for sends/receives on this socket.
-Note #1: an implementation may choose to cap or round the buffer size when setting the value.
-In other words, after setting a value, reading the same setting back may return a different value.
-Note #2: there is not necessarily a direct relationship between the kernel buffer size and the bytes of
-actual data to be sent/received by the application, because the kernel might also use the buffer space
-for internal metadata structures.
+If the provided value is 0, an invalid-argument error is returned.
+Any other value will never cause an error, but it might be silently clamped and/or rounded.
+I.e. after setting a value, reading the same setting back may return a different value.
Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
Typical errors
-already-connected: (set) The socket is already in the Connection state.already-listening: (set) The socket is already in the Listener state.concurrency-conflict: (set) A bind, connect or listen operation is already in progress. (EALREADY)invalid-argument: (set) The provided value was 0.invalid-state: (set) The socket is already in the Connection state.invalid-state: (set) The socket is already in the Listener state.
Params
@@ -1474,7 +1694,7 @@ operations on the output-stream associ
The shutdown function does not close (drop) the socket.
Typical errors
-not-connected: The socket is not in the Connection state. (ENOTCONN)invalid-state: The socket is not in the Connection state. (ENOTCONN)
References
@@ -1492,7 +1712,7 @@ operations on the output-stream associ
-
+
Types
@@ -1518,9 +1738,8 @@ is called, the socket is effectively an in-memory configuration object, unable t
All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.
Typical errors
-not-supported: The host does not support TCP sockets. (EOPNOTSUPP)address-family-not-supported: The specified address-family is not supported. (EAFNOSUPPORT)new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)not-supported: The specified address-family is not supported. (EAFNOSUPPORT)new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
References
@@ -1537,7 +1756,7 @@ is called, the socket is effectively an in-memory configuration object, unable t
-
+
Types
@@ -1552,35 +1771,21 @@ is called, the socket is effectively an in-memory configuration object, unable t
#### `type ip-address`
[`ip-address`](#ip_address)
-#### `type ip-address-family`
-[`ip-address-family`](#ip_address_family)
-
#### `resource resolve-address-stream`
Functions
Resolve an internet host name to a list of IP addresses.
+Unicode domain names are automatically converted to ASCII using IDNA encoding.
+If the input is an IP address string, the address is parsed and returned
+as-is without making any external requests.
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.
+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.
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)invalid-argument: name is a syntactically invalid domain name or IP address.
References:
@@ -1593,8 +1798,6 @@ to resolve-next-address never returns ok(none). This m
Return values
diff --git a/wit/deps.lock b/wit/deps.lock
index 472b87f..be53c76 100644
--- a/wit/deps.lock
+++ b/wit/deps.lock
@@ -1,4 +1,9 @@
+[clocks]
+url = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz"
+sha256 = "89da8eca4cd195516574c89c5b3c24a7b5af3ff2565c16753d20d3bdbc5fc60f"
+sha512 = "244079b3f592d58478a97adbd0bee8d49ae9dd1a3e435651ee40997b50da9fe62cfaba7e3ec7f7406d7d0288d278a43a3a0bc5150226ba40ce0f8ac6d33f7ddb"
+
[io]
url = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz"
-sha256 = "fb76f4449eea54d06b56fc6a7ca988da51bd84a54d2021cf18da67b5e2c7ebcf"
-sha512 = "c005e2a91522958a9537827a49ae344e1cb39d66e85492901a86bcc7e322ba8d0a7f1a02c9b9f840c123b4ad97e297355fac98d4822536d1426d1096dd1d73ac"
+sha256 = "f2e6127b235c37c06be675a904d6acf08db953ea688d78c42892c6ad3bd194e4"
+sha512 = "32feefbc115c34bf6968cb6e9dc15e755698ee90648e5a5d84448917c36a318bd61b401195eb64330e2475e1d098bfb8dee1440d594a68e0797748762bd84ae5"
diff --git a/wit/deps.toml b/wit/deps.toml
index b178cb2..c07efaf 100644
--- a/wit/deps.toml
+++ b/wit/deps.toml
@@ -1 +1,2 @@
+clocks = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz"
io = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz"
diff --git a/wit/deps/clocks/monotonic-clock.wit b/wit/deps/clocks/monotonic-clock.wit
new file mode 100644
index 0000000..09ef32c
--- /dev/null
+++ b/wit/deps/clocks/monotonic-clock.wit
@@ -0,0 +1,45 @@
+package wasi:clocks@0.2.0-rc-2023-11-10;
+/// 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-rc-2023-11-10.{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;
+}
diff --git a/wit/deps/clocks/wall-clock.wit b/wit/deps/clocks/wall-clock.wit
new file mode 100644
index 0000000..8abb9a0
--- /dev/null
+++ b/wit/deps/clocks/wall-clock.wit
@@ -0,0 +1,42 @@
+package wasi:clocks@0.2.0-rc-2023-11-10;
+/// 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;
+}
diff --git a/wit/deps/clocks/world.wit b/wit/deps/clocks/world.wit
new file mode 100644
index 0000000..8fa080f
--- /dev/null
+++ b/wit/deps/clocks/world.wit
@@ -0,0 +1,6 @@
+package wasi:clocks@0.2.0-rc-2023-11-10;
+
+world imports {
+ import monotonic-clock;
+ import wall-clock;
+}
diff --git a/wit/deps/io/error.wit b/wit/deps/io/error.wit
new file mode 100644
index 0000000..31918ac
--- /dev/null
+++ b/wit/deps/io/error.wit
@@ -0,0 +1,34 @@
+package wasi:io@0.2.0-rc-2023-11-10;
+
+
+interface error {
+ /// A resource which represents some error information.
+ ///
+ /// The only method provided by this resource is `to-debug-string`,
+ /// which provides some human-readable information about the error.
+ ///
+ /// In the `wasi:io` package, this resource is returned through the
+ /// `wasi:io/streams/stream-error` type.
+ ///
+ /// To provide more specific error information, other interfaces may
+ /// provide functions to further "downcast" this error into more specific
+ /// error information. For example, `error`s returned in streams derived
+ /// from filesystem types to be described using the filesystem's own
+ /// error-code type, using the function
+ /// `wasi:filesystem/types/filesystem-error-code`, which takes a parameter
+ /// `borrow` and returns
+ /// `option`.
+ ///
+ /// The set of functions which can "downcast" an `error` into a more
+ /// concrete type is open.
+ resource error {
+ /// Returns a string that is suitable to assist humans in debugging
+ /// this error.
+ ///
+ /// WARNING: The returned string should not be consumed mechanically!
+ /// It may change across platforms, hosts, or other implementation
+ /// details. Parsing this string is a major platform-compatibility
+ /// hazard.
+ to-debug-string: func() -> string;
+ }
+}
diff --git a/wit/deps/io/poll.wit b/wit/deps/io/poll.wit
index 0829a7d..bddde3c 100644
--- a/wit/deps/io/poll.wit
+++ b/wit/deps/io/poll.wit
@@ -1,4 +1,4 @@
-package wasi:io;
+package wasi:io@0.2.0-rc-2023-11-10;
/// A poll API intended to let users wait for I/O events on multiple handles
/// at once.
diff --git a/wit/deps/io/streams.wit b/wit/deps/io/streams.wit
index 8999b28..e7e1b68 100644
--- a/wit/deps/io/streams.wit
+++ b/wit/deps/io/streams.wit
@@ -1,4 +1,4 @@
-package wasi:io;
+package wasi:io@0.2.0-rc-2023-11-10;
/// WASI I/O is an I/O abstraction API which is currently focused on providing
/// stream types.
@@ -6,6 +6,7 @@ package wasi:io;
/// In the future, the component model is expected to add built-in stream types;
/// when it does, they are expected to subsume this API.
interface streams {
+ use error.{error};
use poll.{pollable};
/// An error for input-stream and output-stream operations.
@@ -20,26 +21,6 @@ interface streams {
closed
}
- /// Contextual error information about the last failure that happened on
- /// a read, write, or flush from an `input-stream` or `output-stream`.
- ///
- /// This type is returned through the `stream-error` 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 `flush` or `check-write`.
- ///
- /// Interfaces such as `wasi:filesystem/types` provide functionality to
- /// further "downcast" this error into interface-specific error information.
- resource error {
- /// Returns a string that's suitable to assist humans in debugging this
- /// error.
- ///
- /// The returned string will change across platforms and hosts which
- /// means that parsing it, for example, would be a
- /// platform-compatibility hazard.
- to-debug-string: func() -> string;
- }
-
/// An input bytestream.
///
/// `input-stream`s are *non-blocking* to the extent practical on underlying
diff --git a/wit/deps/io/world.wit b/wit/deps/io/world.wit
index 05244a9..8243da2 100644
--- a/wit/deps/io/world.wit
+++ b/wit/deps/io/world.wit
@@ -1,4 +1,4 @@
-package wasi:io;
+package wasi:io@0.2.0-rc-2023-11-10;
world imports {
import streams;
diff --git a/wit/ip-name-lookup.wit b/wit/ip-name-lookup.wit
index 22113ae..931ccf7 100644
--- a/wit/ip-name-lookup.wit
+++ b/wit/ip-name-lookup.wit
@@ -1,50 +1,40 @@
interface ip-name-lookup {
- use wasi:io/poll.{pollable};
- use network.{network, error-code, ip-address, ip-address-family};
+ use wasi:io/poll@0.2.0-rc-2023-11-10.{pollable};
+ use network.{network, error-code, ip-address};
/// Resolve an internet host name to a list of IP addresses.
- ///
+ ///
+ /// Unicode domain names are automatically converted to ASCII using IDNA encoding.
+ /// If the input is an IP address string, the address is parsed and returned
+ /// as-is without making any external requests.
+ ///
/// 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.
- ///
+ ///
+ /// 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.
+ ///
/// # 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)
- ///
+ /// - `invalid-argument`: `name` is a syntactically invalid domain name or IP address.
+ ///
/// # References:
/// -
/// -
/// -
/// -
- resolve-addresses: func(network: borrow, name: string, address-family: option, include-unavailable: bool) -> result;
+ resolve-addresses: func(network: borrow, name: string) -> result;
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)
@@ -53,7 +43,7 @@ interface ip-name-lookup {
resolve-next-address: func() -> result, 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;
diff --git a/wit/network.wit b/wit/network.wit
index 901a4a8..6bb07cd 100644
--- a/wit/network.wit
+++ b/wit/network.wit
@@ -6,7 +6,7 @@ interface network {
resource network;
/// Error codes.
- ///
+ ///
/// In theory, every API can return any error code.
/// In practice, API's typically only return the errors documented per API
/// combined with a couple of errors that are always possible:
@@ -14,7 +14,8 @@ interface network {
/// - `access-denied`
/// - `not-supported`
/// - `out-of-memory`
- ///
+ /// - `concurrency-conflict`
+ ///
/// See each individual API for what the POSIX equivalents are. They sometimes differ per API.
enum error-code {
// ### GENERAL ERRORS ###
@@ -23,17 +24,22 @@ interface network {
unknown,
/// Access denied.
- ///
+ ///
/// POSIX equivalent: EACCES, EPERM
access-denied,
/// The operation is not supported.
- ///
+ ///
/// POSIX equivalent: EOPNOTSUPP
not-supported,
+ /// One of the arguments is invalid.
+ ///
+ /// POSIX equivalent: EINVAL
+ invalid-argument,
+
/// Not enough memory to complete the operation.
- ///
+ ///
/// POSIX equivalent: ENOMEM, ENOBUFS, EAI_MEMORY
out-of-memory,
@@ -41,96 +47,59 @@ interface network {
timeout,
/// This operation is incompatible with another asynchronous operation that is already in progress.
+ ///
+ /// POSIX equivalent: EALREADY
concurrency-conflict,
/// Trying to finish an asynchronous operation that:
/// - has not been started yet, or:
/// - was already finished by a previous `finish-*` call.
- ///
+ ///
/// Note: this is scheduled to be removed when `future`s are natively supported.
not-in-progress,
/// The operation has been aborted because it could not be completed immediately.
- ///
+ ///
/// Note: this is scheduled to be removed when `future`s are natively supported.
would-block,
- // ### IP ERRORS ###
-
- /// The specified address-family is not supported.
- address-family-not-supported,
-
- /// An IPv4 address was passed to an IPv6 resource, or vice versa.
- address-family-mismatch,
-
- /// The socket address is not a valid remote address. E.g. the IP address is set to INADDR_ANY, or the port is set to 0.
- invalid-remote-address,
-
- /// The operation is only supported on IPv4 resources.
- ipv4-only-operation,
-
- /// The operation is only supported on IPv6 resources.
- ipv6-only-operation,
-
-
// ### TCP & UDP SOCKET ERRORS ###
+ /// The operation is not valid in the socket's current state.
+ invalid-state,
+
/// A new socket resource could not be created because of a system limit.
new-socket-limit,
-
- /// The socket is already attached to another network.
- already-attached,
-
- /// The socket is already bound.
- already-bound,
-
- /// The socket is already in the Connection state.
- already-connected,
-
- /// The socket is not bound to any local address.
- not-bound,
-
- /// The socket is not in the Connection state.
- not-connected,
/// A bind operation failed because the provided address is not an address that the `network` can bind to.
address-not-bindable,
- /// A bind operation failed because the provided address is already in use.
+ /// A bind operation failed because the provided address is already in use or because there are no ephemeral ports available.
address-in-use,
- /// A bind operation failed because there are no ephemeral ports available.
- ephemeral-ports-exhausted,
-
/// The remote address is not reachable
remote-unreachable,
-
- // ### TCP SOCKET ERRORS ###
-
- /// The socket is already in the Listener state.
- already-listening,
- /// The socket is already in the Listener state.
- not-listening,
+ // ### TCP SOCKET ERRORS ###
/// The connection was forcefully rejected
connection-refused,
/// The connection was reset.
connection-reset,
-
+
+ /// A connection was aborted.
+ connection-aborted,
+
// ### UDP SOCKET ERRORS ###
datagram-too-large,
// ### NAME LOOKUP ERRORS ###
-
- /// The provided name is a syntactically invalid domain name.
- invalid-name,
/// Name does not exist or has no suitable associated IP addresses.
name-unresolvable,
@@ -144,7 +113,7 @@ interface network {
enum ip-address-family {
/// Similar to `AF_INET` in POSIX.
- ipv4,
+ ipv4,
/// Similar to `AF_INET6` in POSIX.
ipv6,
diff --git a/wit/tcp-create-socket.wit b/wit/tcp-create-socket.wit
index cc4c6fa..768a07c 100644
--- a/wit/tcp-create-socket.wit
+++ b/wit/tcp-create-socket.wit
@@ -4,20 +4,19 @@ interface tcp-create-socket {
use tcp.{tcp-socket};
/// Create a new TCP socket.
- ///
+ ///
/// Similar to `socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP)` in POSIX.
- ///
+ ///
/// This function does not require a network capability handle. This is considered to be safe because
/// at time of creation, the socket is not bound to any `network` yet. Up to the moment `bind`/`listen`/`connect`
/// is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world.
- ///
+ ///
/// All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.
- ///
+ ///
/// # Typical errors
- /// - `not-supported`: The host does not support TCP sockets. (EOPNOTSUPP)
- /// - `address-family-not-supported`: The specified `address-family` is not supported. (EAFNOSUPPORT)
- /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
- ///
+ /// - `not-supported`: The specified `address-family` is not supported. (EAFNOSUPPORT)
+ /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
+ ///
/// # References
/// -
/// -
diff --git a/wit/tcp.wit b/wit/tcp.wit
index 1de68a7..b01b65e 100644
--- a/wit/tcp.wit
+++ b/wit/tcp.wit
@@ -1,7 +1,8 @@
interface tcp {
- use wasi:io/streams.{input-stream, output-stream};
- use wasi:io/poll.{pollable};
+ use wasi:io/streams@0.2.0-rc-2023-11-10.{input-stream, output-stream};
+ use wasi:io/poll@0.2.0-rc-2023-11-10.{pollable};
+ use wasi:clocks/monotonic-clock@0.2.0-rc-2023-11-10.{duration};
use network.{network, error-code, ip-socket-address, ip-address-family};
enum shutdown-type {
@@ -23,24 +24,25 @@ interface tcp {
/// If the IP address is zero (`0.0.0.0` in IPv4, `::` in IPv6), it is left to the implementation to decide which
/// network interface(s) to bind to.
/// If the TCP/UDP port is zero, the socket will be bound to a random free port.
- ///
+ ///
/// When a socket is not explicitly bound, the first invocation to a listen or connect operation will
/// implicitly bind the socket.
- ///
+ ///
/// Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
- ///
+ ///
/// # Typical `start` errors
- /// - `address-family-mismatch`: The `local-address` has the wrong address family. (EINVAL)
- /// - `already-bound`: The socket is already bound. (EINVAL)
- /// - `concurrency-conflict`: Another `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
- ///
+ /// - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
+ /// - `invalid-argument`: `local-address` is not a unicast address. (EINVAL)
+ /// - `invalid-argument`: `local-address` is an IPv4-mapped IPv6 address, but the socket has `ipv6-only` enabled. (EINVAL)
+ /// - `invalid-state`: The socket is already bound. (EINVAL)
+ ///
/// # Typical `finish` errors
- /// - `ephemeral-ports-exhausted`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
+ /// - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
/// - `address-in-use`: Address is already in use. (EADDRINUSE)
/// - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
/// - `not-in-progress`: A `bind` operation is not in progress.
/// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
- ///
+ ///
/// # References
/// -
/// -
@@ -50,29 +52,41 @@ interface tcp {
finish-bind: func() -> result<_, error-code>;
/// Connect to a remote endpoint.
- ///
+ ///
/// On success:
/// - the socket is transitioned into the Connection state
/// - a pair of streams is returned that can be used to read & write to the connection
- ///
+ ///
+ /// POSIX mentions:
+ /// > If connect() fails, the state of the socket is unspecified. Conforming applications should
+ /// > close the file descriptor and create a new socket before attempting to reconnect.
+ ///
+ /// WASI prescribes the following behavior:
+ /// - If `connect` fails because an input/state validation error, the socket should remain usable.
+ /// - If a connection was actually attempted but failed, the socket should become unusable for further network communication.
+ /// Besides `drop`, any method after such a failure may return an error.
+ ///
/// # Typical `start` errors
- /// - `address-family-mismatch`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
- /// - `invalid-remote-address`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EADDRNOTAVAIL on Windows)
- /// - `invalid-remote-address`: The port in `remote-address` is set to 0. (EADDRNOTAVAIL on Windows)
- /// - `already-attached`: The socket is already attached to a different network. The `network` passed to `connect` must be identical to the one passed to `bind`.
- /// - `already-connected`: The socket is already in the Connection state. (EISCONN)
- /// - `already-listening`: The socket is already in the Listener state. (EOPNOTSUPP, EINVAL on Windows)
- /// - `concurrency-conflict`: Another `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
- ///
+ /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
+ /// - `invalid-argument`: `remote-address` is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)
+ /// - `invalid-argument`: `remote-address` is an IPv4-mapped IPv6 address, but the socket has `ipv6-only` enabled. (EINVAL, EADDRNOTAVAIL on Illumos)
+ /// - `invalid-argument`: `remote-address` is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)
+ /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EADDRNOTAVAIL on Windows)
+ /// - `invalid-argument`: The port in `remote-address` is set to 0. (EADDRNOTAVAIL on Windows)
+ /// - `invalid-argument`: The socket is already attached to a different network. The `network` passed to `connect` must be identical to the one passed to `bind`.
+ /// - `invalid-state`: The socket is already in the Connection state. (EISCONN)
+ /// - `invalid-state`: The socket is already in the Listener state. (EOPNOTSUPP, EINVAL on Windows)
+ ///
/// # Typical `finish` errors
/// - `timeout`: Connection timed out. (ETIMEDOUT)
/// - `connection-refused`: The connection was forcefully rejected. (ECONNREFUSED)
/// - `connection-reset`: The connection was reset. (ECONNRESET)
- /// - `remote-unreachable`: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN)
- /// - `ephemeral-ports-exhausted`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
+ /// - `connection-aborted`: The connection was aborted. (ECONNABORTED)
+ /// - `remote-unreachable`: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
+ /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
/// - `not-in-progress`: A `connect` operation is not in progress.
/// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
- ///
+ ///
/// # References
/// -
/// -
@@ -82,21 +96,20 @@ interface tcp {
finish-connect: func() -> result, error-code>;
/// Start listening for new connections.
- ///
+ ///
/// Transitions the socket into the Listener state.
- ///
+ ///
/// Unlike POSIX:
/// - this function is async. This enables interactive WASI hosts to inject permission prompts.
/// - the socket must already be explicitly bound.
- ///
+ ///
/// # Typical `start` errors
- /// - `not-bound`: The socket is not bound to any local address. (EDESTADDRREQ)
- /// - `already-connected`: The socket is already in the Connection state. (EISCONN, EINVAL on BSD)
- /// - `already-listening`: The socket is already in the Listener state.
- /// - `concurrency-conflict`: Another `bind`, `connect` or `listen` operation is already in progress. (EINVAL on BSD)
+ /// - `invalid-state`: The socket is not bound to any local address. (EDESTADDRREQ)
+ /// - `invalid-state`: The socket is already in the Connection state. (EISCONN, EINVAL on BSD)
+ /// - `invalid-state`: The socket is already in the Listener state.
///
/// # Typical `finish` errors
- /// - `ephemeral-ports-exhausted`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)
+ /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)
/// - `not-in-progress`: A `listen` operation is not in progress.
/// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
///
@@ -109,18 +122,27 @@ interface tcp {
finish-listen: func() -> result<_, error-code>;
/// Accept a new client socket.
- ///
- /// The returned socket is bound and in the Connection state.
- ///
+ ///
+ /// The returned socket is bound and in the Connection state. The following properties are inherited from the listener socket:
+ /// - `address-family`
+ /// - `ipv6-only`
+ /// - `keep-alive-enabled`
+ /// - `keep-alive-idle-time`
+ /// - `keep-alive-interval`
+ /// - `keep-alive-count`
+ /// - `hop-limit`
+ /// - `receive-buffer-size`
+ /// - `send-buffer-size`
+ ///
/// On success, this function returns the newly accepted client socket along with
/// a pair of streams that can be used to read & write to the connection.
- ///
+ ///
/// # Typical errors
- /// - `not-listening`: Socket is not in the Listener state. (EINVAL)
- /// - `would-block`: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)
- ///
- /// Host implementations must skip over transient errors returned by the native accept syscall.
- ///
+ /// - `invalid-state`: Socket is not in the Listener state. (EINVAL)
+ /// - `would-block`: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)
+ /// - `connection-aborted`: An incoming connection was pending, but was terminated by the client before this listener could accept it. (ECONNABORTED)
+ /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
+ ///
/// # References
/// -
/// -
@@ -129,10 +151,16 @@ interface tcp {
accept: func() -> result, error-code>;
/// Get the bound local address.
- ///
+ ///
+ /// POSIX mentions:
+ /// > If the socket has not been bound to a local name, the value
+ /// > stored in the object pointed to by `address` is unspecified.
+ ///
+ /// WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet.
+ ///
/// # Typical errors
- /// - `not-bound`: The socket is not bound to any local address.
- ///
+ /// - `invalid-state`: The socket is not bound to any local address.
+ ///
/// # References
/// -
/// -
@@ -140,11 +168,11 @@ interface tcp {
/// -
local-address: func() -> result;
- /// Get the bound remote address.
- ///
+ /// Get the remote address.
+ ///
/// # Typical errors
- /// - `not-connected`: The socket is not connected to a remote address. (ENOTCONN)
- ///
+ /// - `invalid-state`: The socket is not connected to a remote address. (ENOTCONN)
+ ///
/// # References
/// -
/// -
@@ -152,93 +180,137 @@ interface tcp {
/// -
remote-address: func() -> result;
+ /// Whether the socket is listening for new connections.
+ ///
+ /// Equivalent to the SO_ACCEPTCONN socket option.
+ is-listening: func() -> bool;
+
/// Whether this is a IPv4 or IPv6 socket.
- ///
+ ///
/// Equivalent to the SO_DOMAIN socket option.
address-family: func() -> ip-address-family;
-
+
/// Whether IPv4 compatibility (dual-stack) mode is disabled or not.
- ///
+ ///
/// Equivalent to the IPV6_V6ONLY socket option.
- ///
+ ///
/// # Typical errors
- /// - `ipv6-only-operation`: (get/set) `this` socket is an IPv4 socket.
- /// - `already-bound`: (set) The socket is already bound.
+ /// - `invalid-state`: (set) The socket is already bound.
+ /// - `not-supported`: (get/set) `this` socket is an IPv4 socket.
/// - `not-supported`: (set) Host does not support dual-stack sockets. (Implementations are not required to.)
- /// - `concurrency-conflict`: (set) A `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
ipv6-only: func() -> result;
set-ipv6-only: func(value: bool) -> result<_, error-code>;
/// Hints the desired listen queue size. Implementations are free to ignore this.
- ///
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
+ ///
/// # Typical errors
- /// - `already-connected`: (set) The socket is already in the Connection state.
- /// - `concurrency-conflict`: (set) A `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
+ /// - `not-supported`: (set) The platform does not support changing the backlog size after the initial listen.
+ /// - `invalid-argument`: (set) The provided value was 0.
+ /// - `invalid-state`: (set) The socket is already in the Connection state.
set-listen-backlog-size: func(value: u64) -> result<_, error-code>;
+ /// Enables or disables keepalive.
+ ///
+ /// The keepalive behavior can be adjusted using:
+ /// - `keep-alive-idle-time`
+ /// - `keep-alive-interval`
+ /// - `keep-alive-count`
+ /// These properties can be configured while `keep-alive-enabled` is false, but only come into effect when `keep-alive-enabled` is true.
+ ///
/// Equivalent to the SO_KEEPALIVE socket option.
- ///
+ keep-alive-enabled: func() -> result;
+ set-keep-alive-enabled: func(value: bool) -> result<_, error-code>;
+
+ /// Amount of time the connection has to be idle before TCP starts sending keepalive packets.
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
+ /// I.e. after setting a value, reading the same setting back may return a different value.
+ ///
+ /// Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: (set) The provided value was 0.
+ keep-alive-idle-time: func() -> result;
+ set-keep-alive-idle-time: func(value: duration) -> result<_, error-code>;
+
+ /// The time between keepalive packets.
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
+ /// I.e. after setting a value, reading the same setting back may return a different value.
+ ///
+ /// Equivalent to the TCP_KEEPINTVL socket option.
+ ///
/// # Typical errors
- /// - `concurrency-conflict`: (set) A `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
- keep-alive: func() -> result;
- set-keep-alive: func(value: bool) -> result<_, error-code>;
+ /// - `invalid-argument`: (set) The provided value was 0.
+ keep-alive-interval: func() -> result;
+ set-keep-alive-interval: func(value: duration) -> result<_, error-code>;
- /// Equivalent to the TCP_NODELAY socket option.
- ///
+ /// The maximum amount of keepalive packets TCP should send before aborting the connection.
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
+ /// I.e. after setting a value, reading the same setting back may return a different value.
+ ///
+ /// Equivalent to the TCP_KEEPCNT socket option.
+ ///
/// # Typical errors
- /// - `concurrency-conflict`: (set) A `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
- no-delay: func() -> result;
- set-no-delay: func(value: bool) -> result<_, error-code>;
-
+ /// - `invalid-argument`: (set) The provided value was 0.
+ keep-alive-count: func() -> result;
+ set-keep-alive-count: func(value: u32) -> result<_, error-code>;
+
/// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
- ///
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ ///
/// # Typical errors
- /// - `already-connected`: (set) The socket is already in the Connection state.
- /// - `already-listening`: (set) The socket is already in the Listener state.
- /// - `concurrency-conflict`: (set) A `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
- unicast-hop-limit: func() -> result;
- set-unicast-hop-limit: func(value: u8) -> result<_, error-code>;
+ /// - `invalid-argument`: (set) The TTL value must be 1 or higher.
+ /// - `invalid-state`: (set) The socket is already in the Connection state.
+ /// - `invalid-state`: (set) The socket is already in the Listener state.
+ hop-limit: func() -> result;
+ set-hop-limit: func(value: u8) -> result<_, error-code>;
/// The kernel buffer space reserved for sends/receives on this socket.
- ///
- /// Note #1: an implementation may choose to cap or round the buffer size when setting the value.
- /// In other words, after setting a value, reading the same setting back may return a different value.
- ///
- /// Note #2: there is not necessarily a direct relationship between the kernel buffer size and the bytes of
- /// actual data to be sent/received by the application, because the kernel might also use the buffer space
- /// for internal metadata structures.
- ///
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
+ /// I.e. after setting a value, reading the same setting back may return a different value.
+ ///
/// Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
- ///
+ ///
/// # Typical errors
- /// - `already-connected`: (set) The socket is already in the Connection state.
- /// - `already-listening`: (set) The socket is already in the Listener state.
- /// - `concurrency-conflict`: (set) A `bind`, `connect` or `listen` operation is already in progress. (EALREADY)
+ /// - `invalid-argument`: (set) The provided value was 0.
+ /// - `invalid-state`: (set) The socket is already in the Connection state.
+ /// - `invalid-state`: (set) The socket is already in the Listener state.
receive-buffer-size: func() -> result;
set-receive-buffer-size: func(value: u64) -> result<_, error-code>;
send-buffer-size: func() -> result;
set-send-buffer-size: func(value: u64) -> result<_, error-code>;
/// Create a `pollable` which will resolve once the socket 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;
/// Initiate a graceful shutdown.
- ///
+ ///
/// - receive: the socket is not expecting to receive any more data from the peer. All subsequent read
/// operations on the `input-stream` associated with this socket will return an End Of Stream indication.
/// Any data still in the receive queue at time of calling `shutdown` will be discarded.
/// - send: the socket is not expecting to send any more data to the peer. All subsequent write
/// operations on the `output-stream` associated with this socket will return an error.
/// - both: same effect as receive & send combined.
- ///
+ ///
/// The shutdown function does not close (drop) the socket.
- ///
+ ///
/// # Typical errors
- /// - `not-connected`: The socket is not in the Connection state. (ENOTCONN)
- ///
+ /// - `invalid-state`: The socket is not in the Connection state. (ENOTCONN)
+ ///
/// # References
/// -
/// -
diff --git a/wit/udp-create-socket.wit b/wit/udp-create-socket.wit
index 3358e2c..cc58234 100644
--- a/wit/udp-create-socket.wit
+++ b/wit/udp-create-socket.wit
@@ -4,20 +4,19 @@ interface udp-create-socket {
use udp.{udp-socket};
/// Create a new UDP socket.
- ///
+ ///
/// Similar to `socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP)` in POSIX.
- ///
+ ///
/// This function does not require a network capability handle. This is considered to be safe because
- /// at time of creation, the socket is not bound to any `network` yet. Up to the moment `bind`/`connect` is called,
+ /// at time of creation, the socket is not bound to any `network` yet. Up to the moment `bind` is called,
/// the socket is effectively an in-memory configuration object, unable to communicate with the outside world.
- ///
+ ///
/// All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.
- ///
+ ///
/// # Typical errors
- /// - `not-supported`: The host does not support UDP sockets. (EOPNOTSUPP)
- /// - `address-family-not-supported`: The specified `address-family` is not supported. (EAFNOSUPPORT)
- /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
- ///
+ /// - `not-supported`: The specified `address-family` is not supported. (EAFNOSUPPORT)
+ /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
+ ///
/// # References:
/// -
/// -
diff --git a/wit/udp.wit b/wit/udp.wit
index ca497b3..c8dafad 100644
--- a/wit/udp.wit
+++ b/wit/udp.wit
@@ -1,19 +1,36 @@
interface udp {
- use wasi:io/poll.{pollable};
+ use wasi:io/poll@0.2.0-rc-2023-11-10.{pollable};
use network.{network, error-code, ip-socket-address, ip-address-family};
+ /// A received datagram.
+ record incoming-datagram {
+ /// The payload.
+ ///
+ /// Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes.
+ data: list,
- record datagram {
- data: list, // Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes.
+ /// The source address.
+ ///
+ /// This field is guaranteed to match the remote address the stream was initialized with, if any.
+ ///
+ /// Equivalent to the `src_addr` out parameter of `recvfrom`.
remote-address: ip-socket-address,
+ }
+
+ /// A datagram to be sent out.
+ record outgoing-datagram {
+ /// The payload.
+ data: list,
- /// Possible future additions:
- /// local-address: ip-socket-address, // IP_PKTINFO / IP_RECVDSTADDR / IPV6_PKTINFO
- /// local-interface: u32, // IP_PKTINFO / IP_RECVIF
- /// ttl: u8, // IP_RECVTTL
- /// dscp: u6, // IP_RECVTOS
- /// ecn: u2, // IP_RECVTOS
+ /// The destination address.
+ ///
+ /// The requirements on this field depend on how the stream was initialized:
+ /// - with a remote address: this field must be None or match the stream's remote address exactly.
+ /// - without a remote address: this field is required.
+ ///
+ /// If this value is None, the send operation is equivalent to `send` in POSIX. Otherwise it is equivalent to `sendto`.
+ remote-address: option,
}
@@ -24,24 +41,21 @@ interface udp {
///
/// If the IP address is zero (`0.0.0.0` in IPv4, `::` in IPv6), it is left to the implementation to decide which
/// network interface(s) to bind to.
- /// If the TCP/UDP port is zero, the socket will be bound to a random free port.
- ///
- /// When a socket is not explicitly bound, the first invocation to connect will implicitly bind the socket.
- ///
+ /// If the port is zero, the socket will be bound to a random free port.
+ ///
/// Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
- ///
+ ///
/// # Typical `start` errors
- /// - `address-family-mismatch`: The `local-address` has the wrong address family. (EINVAL)
- /// - `already-bound`: The socket is already bound. (EINVAL)
- /// - `concurrency-conflict`: Another `bind` or `connect` operation is already in progress. (EALREADY)
- ///
+ /// - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
+ /// - `invalid-state`: The socket is already bound. (EINVAL)
+ ///
/// # Typical `finish` errors
- /// - `ephemeral-ports-exhausted`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
+ /// - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
/// - `address-in-use`: Address is already in use. (EADDRINUSE)
/// - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
/// - `not-in-progress`: A `bind` operation is not in progress.
/// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
- ///
+ ///
/// # References
/// -
/// -
@@ -50,100 +64,60 @@ interface udp {
start-bind: func(network: borrow, local-address: ip-socket-address) -> result<_, error-code>;
finish-bind: func() -> result<_, error-code>;
- /// Set the destination address.
- ///
- /// The local-address is updated based on the best network path to `remote-address`.
- ///
- /// When a destination address is set:
- /// - all receive operations will only return datagrams sent from the provided `remote-address`.
- /// - the `send` function can only be used to send to this destination.
- ///
- /// Note that this function does not generate any network traffic and the peer is not aware of this "connection".
- ///
- /// Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
- ///
- /// # Typical `start` errors
- /// - `address-family-mismatch`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
- /// - `invalid-remote-address`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
- /// - `invalid-remote-address`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
- /// - `already-attached`: The socket is already bound to a different network. The `network` passed to `connect` must be identical to the one passed to `bind`.
- /// - `concurrency-conflict`: Another `bind` or `connect` operation is already in progress. (EALREADY)
- ///
- /// # Typical `finish` errors
- /// - `ephemeral-ports-exhausted`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
- /// - `not-in-progress`: A `connect` operation is not in progress.
- /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
+ /// Set up inbound & outbound communication channels, optionally to a specific peer.
+ ///
+ /// This function only changes the local socket configuration and does not generate any network traffic.
+ /// On success, the `remote-address` of the socket is updated. The `local-address` may be updated as well,
+ /// based on the best network path to `remote-address`.
+ ///
+ /// When a `remote-address` is provided, the returned streams are limited to communicating with that specific peer:
+ /// - `send` can only be used to send to this destination.
+ /// - `receive` will only return datagrams sent from the provided `remote-address`.
+ ///
+ /// This method may be called multiple times on the same socket to change its association, but
+ /// only the most recently returned pair of streams will be operational. Implementations may trap if
+ /// the streams returned by a previous invocation haven't been dropped yet before calling `stream` again.
+ ///
+ /// The POSIX equivalent in pseudo-code is:
+ /// ```text
+ /// if (was previously connected) {
+ /// connect(s, AF_UNSPEC)
+ /// }
+ /// if (remote_address is Some) {
+ /// connect(s, remote_address)
+ /// }
+ /// ```
+ ///
+ /// Unlike in POSIX, the socket must already be explicitly bound.
///
+ /// # Typical errors
+ /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
+ /// - `invalid-argument`: `remote-address` is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)
+ /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
+ /// - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
+ /// - `invalid-state`: The socket is not bound.
+ /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
+ /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
+ /// - `connection-refused`: The connection was refused. (ECONNREFUSED)
+ ///
/// # References
/// -
/// -
/// -
/// -
- start-connect: func(network: borrow, remote-address: ip-socket-address) -> result<_, error-code>;
- finish-connect: func() -> result<_, error-code>;
-
- /// Receive messages on the socket.
- ///
- /// This function attempts to receive up to `max-results` datagrams on the socket without blocking.
- /// The returned list may contain fewer elements than requested, but never more.
- /// If `max-results` is 0, this function returns successfully with an empty list.
- ///
- /// # Typical errors
- /// - `not-bound`: The socket is not bound to any local address. (EINVAL)
- /// - `remote-unreachable`: The remote address is not reachable. (ECONNREFUSED, ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN)
- /// - `would-block`: There is no pending data available to be read at the moment. (EWOULDBLOCK, EAGAIN)
- ///
- /// # References
- /// -
- /// -
- /// -
- /// -
- /// -
- /// -
- /// -
- /// -
- receive: func(max-results: u64) -> result, error-code>;
-
- /// Send messages on the socket.
- ///
- /// This function attempts to send all provided `datagrams` on the socket without blocking and
- /// returns how many messages were actually sent (or queued for sending).
- ///
- /// This function semantically behaves the same as iterating the `datagrams` list and sequentially
- /// sending each individual datagram until either the end of the list has been reached or the first error occurred.
- /// If at least one datagram has been sent successfully, this function never returns an error.
- ///
- /// If the input list is empty, the function returns `ok(0)`.
- ///
- /// The remote address option is required. To send a message to the "connected" peer,
- /// call `remote-address` to get their address.
- ///
- /// # Typical errors
- /// - `address-family-mismatch`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
- /// - `invalid-remote-address`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
- /// - `invalid-remote-address`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
- /// - `already-connected`: The socket is in "connected" mode and the `datagram.remote-address` does not match the address passed to `connect`. (EISCONN)
- /// - `not-bound`: The socket is not bound to any local address. Unlike POSIX, this function does not perform an implicit bind.
- /// - `remote-unreachable`: The remote address is not reachable. (ECONNREFUSED, ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN)
- /// - `datagram-too-large`: The datagram is too large. (EMSGSIZE)
- /// - `would-block`: The send buffer is currently full. (EWOULDBLOCK, EAGAIN)
- ///
- /// # References
- /// -
- /// -
- /// -
- /// -
- /// -
- /// -
- /// -
- /// -
- send: func(datagrams: list) -> result;
+ %stream: func(remote-address: option) -> result, error-code>;
/// Get the current bound address.
+ ///
+ /// POSIX mentions:
+ /// > If the socket has not been bound to a local name, the value
+ /// > stored in the object pointed to by `address` is unspecified.
+ ///
+ /// WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet.
///
/// # Typical errors
- /// - `not-bound`: The socket is not bound to any local address.
- ///
+ /// - `invalid-state`: The socket is not bound to any local address.
+ ///
/// # References
/// -
/// -
@@ -151,11 +125,11 @@ interface udp {
/// -
local-address: func() -> result;
- /// Get the address set with `connect`.
- ///
+ /// Get the address the socket is currently streaming to.
+ ///
/// # Typical errors
- /// - `not-connected`: The socket is not connected to a remote address. (ENOTCONN)
- ///
+ /// - `invalid-state`: The socket is not streaming to a specific remote address. (ENOTCONN)
+ ///
/// # References
/// -
/// -
@@ -164,49 +138,138 @@ interface udp {
remote-address: func() -> result;
/// Whether this is a IPv4 or IPv6 socket.
- ///
+ ///
/// Equivalent to the SO_DOMAIN socket option.
address-family: func() -> ip-address-family;
/// Whether IPv4 compatibility (dual-stack) mode is disabled or not.
- ///
+ ///
/// Equivalent to the IPV6_V6ONLY socket option.
- ///
+ ///
/// # Typical errors
- /// - `ipv6-only-operation`: (get/set) `this` socket is an IPv4 socket.
- /// - `already-bound`: (set) The socket is already bound.
+ /// - `not-supported`: (get/set) `this` socket is an IPv4 socket.
+ /// - `invalid-state`: (set) The socket is already bound.
/// - `not-supported`: (set) Host does not support dual-stack sockets. (Implementations are not required to.)
- /// - `concurrency-conflict`: (set) Another `bind` or `connect` operation is already in progress. (EALREADY)
ipv6-only: func() -> result;
set-ipv6-only: func(value: bool) -> result<_, error-code>;
/// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
- ///
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ ///
/// # Typical errors
- /// - `concurrency-conflict`: (set) Another `bind` or `connect` operation is already in progress. (EALREADY)
+ /// - `invalid-argument`: (set) The TTL value must be 1 or higher.
unicast-hop-limit: func() -> result;
set-unicast-hop-limit: func(value: u8) -> result<_, error-code>;
/// The kernel buffer space reserved for sends/receives on this socket.
- ///
- /// Note #1: an implementation may choose to cap or round the buffer size when setting the value.
- /// In other words, after setting a value, reading the same setting back may return a different value.
- ///
- /// Note #2: there is not necessarily a direct relationship between the kernel buffer size and the bytes of
- /// actual data to be sent/received by the application, because the kernel might also use the buffer space
- /// for internal metadata structures.
- ///
+ ///
+ /// If the provided value is 0, an `invalid-argument` error is returned.
+ /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
+ /// I.e. after setting a value, reading the same setting back may return a different value.
+ ///
/// Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
- ///
+ ///
/// # Typical errors
- /// - `concurrency-conflict`: (set) Another `bind` or `connect` operation is already in progress. (EALREADY)
+ /// - `invalid-argument`: (set) The provided value was 0.
receive-buffer-size: func() -> result;
set-receive-buffer-size: func(value: u64) -> result<_, error-code>;
send-buffer-size: func() -> result;
set-send-buffer-size: func(value: u64) -> result<_, error-code>;
/// Create a `pollable` which will resolve once the socket 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;
+ }
+
+ resource incoming-datagram-stream {
+ /// Receive messages on the socket.
+ ///
+ /// This function attempts to receive up to `max-results` datagrams on the socket without blocking.
+ /// The returned list may contain fewer elements than requested, but never more.
+ ///
+ /// This function returns successfully with an empty list when either:
+ /// - `max-results` is 0, or:
+ /// - `max-results` is greater than 0, but no results are immediately available.
+ /// This function never returns `error(would-block)`.
+ ///
+ /// # Typical errors
+ /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
+ /// - `connection-refused`: The connection was refused. (ECONNREFUSED)
+ ///
+ /// # References
+ /// -
+ /// -
+ /// -
+ /// -
+ /// -
+ /// -
+ /// -
+ /// -
+ receive: func(max-results: u64) -> result, error-code>;
+
+ /// Create a `pollable` which will resolve once the stream is ready to receive again.
+ ///
+ /// 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;
+ }
+
+ resource outgoing-datagram-stream {
+ /// Check readiness for sending. This function never blocks.
+ ///
+ /// Returns the number of datagrams permitted for the next call to `send`,
+ /// or an error. Calling `send` with more datagrams than this function has
+ /// permitted will trap.
+ ///
+ /// When this function returns ok(0), the `subscribe` pollable will
+ /// become ready when this function will report at least ok(1), or an
+ /// error.
///
+ /// Never returns `would-block`.
+ check-send: func() -> result;
+
+ /// Send messages on the socket.
+ ///
+ /// This function attempts to send all provided `datagrams` on the socket without blocking and
+ /// returns how many messages were actually sent (or queued for sending). This function never
+ /// returns `error(would-block)`. If none of the datagrams were able to be sent, `ok(0)` is returned.
+ ///
+ /// This function semantically behaves the same as iterating the `datagrams` list and sequentially
+ /// sending each individual datagram until either the end of the list has been reached or the first error occurred.
+ /// If at least one datagram has been sent successfully, this function never returns an error.
+ ///
+ /// If the input list is empty, the function returns `ok(0)`.
+ ///
+ /// Each call to `send` must be permitted by a preceding `check-send`. Implementations must trap if
+ /// either `check-send` was not called or `datagrams` contains more items than `check-send` permitted.
+ ///
+ /// # Typical errors
+ /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
+ /// - `invalid-argument`: `remote-address` is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)
+ /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
+ /// - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
+ /// - `invalid-argument`: The socket is in "connected" mode and `remote-address` is `some` value that does not match the address passed to `stream`. (EISCONN)
+ /// - `invalid-argument`: The socket is not "connected" and no value for `remote-address` was provided. (EDESTADDRREQ)
+ /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
+ /// - `connection-refused`: The connection was refused. (ECONNREFUSED)
+ /// - `datagram-too-large`: The datagram is too large. (EMSGSIZE)
+ ///
+ /// # References
+ /// -
+ /// -
+ /// -
+ /// -
+ /// -
+ /// -
+ /// -
+ /// -
+ send: func(datagrams: list) -> result;
+
+ /// Create a `pollable` which will resolve once the stream is ready to send again.
+ ///
/// 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;
diff --git a/wit/world.wit b/wit/world.wit
index 432b0dc..49ad8d3 100644
--- a/wit/world.wit
+++ b/wit/world.wit
@@ -1,4 +1,4 @@
-package wasi:sockets;
+package wasi:sockets@0.2.0-rc-2023-11-10;
world imports {
import instance-network;