From 7f1234e893ade1422db0c9c84cc01135ab677f77 Mon Sep 17 00:00:00 2001
From: Dave Bakker
access-denied
not-supported
out-of-memory
concurrency-conflict
See each individual API for what the POSIX equivalents are. They sometimes differ per API.
POSIX equivalent: EOPNOTSUPP
One of the arguments is invalid. +
POSIX equivalent: EINVAL
+Not enough memory to complete the operation.
POSIX equivalent: ENOMEM, ENOBUFS, EAI_MEMORY
@@ -58,6 +64,7 @@ combined with a couple of errors that are always possible:This operation is incompatible with another asynchronous operation that is already in progress. +
POSIX equivalent: EALREADY
Note: this is scheduled to be removed when future
s are natively supported.
The specified address-family is not supported. -
An IPv4 address was passed to an IPv6 resource, or vice versa. -
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. -
The operation is only supported on IPv4 resources. -
The operation is only supported on IPv6 resources. +
+The operation is not valid in the socket's current state.
A new socket resource could not be created because of a system limit.
The socket is already attached to another network. -
The socket is already bound. -
The socket is already in the Connection state. -
The socket is not bound to any local address. -
The socket is not in the Connection state. -
A bind operation failed because the provided address is not an address that the `network` can bind to.
A bind operation failed because the provided address is already in use. -
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.
The remote address is not reachable
The socket is already in the Listener state. -
The socket is already in the Listener state. -
The connection was forcefully rejected
The connection was reset.
A connection was aborted.
The provided name is a syntactically invalid domain name. +
-#### `record datagram` +#### `record incoming-datagram` +
A received datagram.
+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
.
record outgoing-datagram
A datagram to be sent out.
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:
+If this value is None, the send operation is equivalent to send
in POSIX. Otherwise it is equivalent to sendto
.
resource udp-socket
resource incoming-datagram-stream
resource outgoing-datagram-stream
[method]udp-socket.start-bind: func
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.
start
errorsaddress-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)finish
errorsephemeral-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.error-code
>[method]udp-socket.start-connect: func
Set the destination address.
-The local-address is updated based on the best network path to remote-address
.
When a destination address is set:
-remote-address
.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.
-start
errorsaddress-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)finish
errors[method]udp-socket.stream: func
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.
+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)self
: borrow<udp-socket
>network
: borrow<network
>remote-address
: ip-socket-address
error-code
>[method]udp-socket.finish-connect: func
self
: borrow<udp-socket
>error-code
>[method]udp-socket.receive: func
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.
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)self
: borrow<udp-socket
>max-results
: u64
datagram
>, error-code
>[method]udp-socket.send: func
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.
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)self
: borrow<udp-socket
>datagrams
: list<datagram
>self
: borrow<udp-socket
>remote-address
: option<ip-socket-address
>u64
, error-code
>incoming-datagram-stream
>, own<outgoing-datagram-stream
>), error-code
>[method]udp-socket.local-address: func
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.
not-bound
: The socket is not bound to any local address.invalid-state
: The socket is not bound to any local address.remote-address
to get their address.
ip-socket-address
, error-code
>[method]udp-socket.remote-address: func
Get the address set with connect
.
Get the address the socket is currently streaming to.
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)remote-address
to get their address.
Equivalent to the IPV6_V6ONLY socket option.
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)remote-address
to get their address.
[method]udp-socket.unicast-hop-limit: func
Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
-concurrency-conflict
: (set) Another bind
or connect
operation is already in progress. (EALREADY)self
: borrow<udp-socket
>Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
-concurrency-conflict
: (set) Another bind
or connect
operation is already in progress. (EALREADY)self
: borrow<udp-socket
>future
is natively supported in Pre
pollable
>[method]incoming-datagram-stream.receive: func
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)
.remote-unreachable
: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)connection-refused
: The connection was refused. (ECONNREFUSED)self
: borrow<incoming-datagram-stream
>max-results
: u64
incoming-datagram
>, error-code
>[method]incoming-datagram-stream.subscribe: func
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.
self
: borrow<incoming-datagram-stream
>pollable
>[method]outgoing-datagram-stream.check-send: func
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
.
self
: borrow<outgoing-datagram-stream
>u64
, error-code
>[method]outgoing-datagram-stream.send: func
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.
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)self
: borrow<outgoing-datagram-stream
>datagrams
: list<outgoing-datagram
>u64
, error-code
>[method]outgoing-datagram-stream.subscribe: func
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.
self
: borrow<outgoing-datagram-stream
>pollable
>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.
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)Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
start
errorsaddress-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)finish
errorsephemeral-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.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:
+connect
fails because an input/state validation error, the socket should remain usable.drop
, any method after such a failure may return an error.start
errorsaddress-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)finish
errorstimeout
: 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)start
errorsnot-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.finish
errorsephemeral-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)[method]tcp-socket.accept: func
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
unicast-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.
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.
[method]tcp-socket.local-address: func
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.
not-bound
: The socket is not bound to any local address.invalid-state
: The socket is not bound to any local address.ip-socket-address
, error-code
>[method]tcp-socket.remote-address: func
Get the bound remote address.
+Get the remote address.
not-connected
: The socket is not connected to a remote address. (ENOTCONN)invalid-state
: The socket is not connected to a remote address. (ENOTCONN)Equivalent to the IPV6_V6ONLY socket option.
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)Hints the desired listen queue size. Implementations are free to ignore this.
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-state
: (set) The socket is already in the Connection state.[method]tcp-socket.keep-alive: func
Equivalent to the SO_KEEPALIVE socket option.
-concurrency-conflict
: (set) A bind
, connect
or listen
operation is already in progress. (EALREADY)self
: borrow<tcp-socket
>error-code
>[method]tcp-socket.no-delay: func
Equivalent to the TCP_NODELAY socket option.
-concurrency-conflict
: (set) A bind
, connect
or listen
operation is already in progress. (EALREADY)self
: borrow<tcp-socket
>bool
, error-code
>[method]tcp-socket.set-no-delay: func
self
: borrow<tcp-socket
>value
: bool
error-code
>[method]tcp-socket.unicast-hop-limit: func
Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
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.Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
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-state
: (set) The socket is already in the Connection state.invalid-state
: (set) The socket is already in the Listener state.output-stream
associ
The shutdown function does not close (drop) the socket.
not-connected
: The socket is not in the Connection state. (ENOTCONN)invalid-state
: The socket is not in the Connection state. (ENOTCONN)All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.
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)-#### `type ip-address-family` -[`ip-address-family`](#ip_address_family) -
#### `resource resolve-address-stream`
resolve-addresses: func
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.
-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: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.
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.resolve-next-address
never returns ok(none)
. This m
network
: borrow<network
>name
: string
address-family
: option<ip-address-family
>include-unavailable
: bool
This interface provides a value-export of the default network handle..
network
>A poll API intended to let users wait for I/O events on multiple handles at once.
type pollable
address
is unspecified.
[method]udp-socket.unicast-hop-limit: func
Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+If the provided value is 0, an invalid-argument
error is returned.
invalid-argument
: (set) The TTL value must be 1 or higher.self
: borrow<udp-socket
>address
is unspecified.
[method]udp-socket.receive-buffer-size: func
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.
+invalid-argument
: (set) The provided value was 0.self
: borrow<udp-socket
>future
is natively supported in Pre
pollable
>type network
udp-socket
>, error-code
>resource error
[method]error.to-debug-string: func
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.
+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.
type pollable
type error
-#### `resource error` -
variant stream-error
+#### `variant stream-error`
An error for input-stream and output-stream operations.
resource output-stream
[method]error.to-debug-string: func
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.
-[method]input-stream.read: func
Perform a non-blocking read from the stream.
This function returns a list of bytes containing the read data,
@@ -1042,7 +1060,68 @@ is ready for reading, before performing the splice
.
u64
, stream-error
>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.
+type 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. +
type duration
u64
A duration of time, in nanoseconds. +
now: func
Read the current value of the clock.
+The clock is monotonic, therefore calling this function repeatedly will +produce a sequence of non-decreasing values.
+instant
resolution: func
Query the resolution of the clock. Returns the duration of time +corresponding to a clock tick.
+duration
subscribe-instant: func
Create a pollable
which will resolve once the specified instant
+occured.
pollable
>subscribe-duration: func
Create a pollable
which will resolve once the given duration has
+elapsed, starting at the time at which this function was called.
+occured.
pollable
>type input-stream
splice
.
#### `type pollable`
[`pollable`](#pollable)
+#### `type duration` +[`duration`](#duration) +
#### `type network` [`network`](#network)
@@ -1251,8 +1333,11 @@ Besides drop
, any method after such a failure may return an error.<
address-family
ipv6-only
keep-alive
unicast-hop-limit
keep-alive-enabled
keep-alive-idle-time
keep-alive-interval
keep-alive-count
hop-limit
receive-buffer-size
send-buffer-size
address
is unspecified.
ip-socket-address
, error-code
>[method]tcp-socket.is-listening: func
Whether the socket is listening for new connections.
+Equivalent to the SO_ACCEPTCONN socket option.
+self
: borrow<tcp-socket
>[method]tcp-socket.address-family: func
Whether this is a IPv4 or IPv6 socket.
Equivalent to the SO_DOMAIN socket option.
@@ -1368,9 +1464,12 @@ stored in the object pointed to byaddress
is unspecified.
[method]tcp-socket.set-listen-backlog-size: func
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.
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.address
is unspecified.
error-code
>[method]tcp-socket.keep-alive: func
[method]tcp-socket.keep-alive-enabled: func
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.
self
: borrow<tcp-socket
>self
: borrow<tcp-socket
>bool
, error-code
>[method]tcp-socket.set-keep-alive-enabled: func
self
: borrow<tcp-socket
>value
: bool
error-code
>[method]tcp-socket.keep-alive-idle-time: func
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)
+invalid-argument
: (set) The provided value was 0.self
: borrow<tcp-socket
>duration
, error-code
>[method]tcp-socket.set-keep-alive-idle-time: func
self
: borrow<tcp-socket
>value
: duration
error-code
>[method]tcp-socket.keep-alive-interval: func
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.
+invalid-argument
: (set) The provided value was 0.self
: borrow<tcp-socket
>duration
, error-code
>[method]tcp-socket.set-keep-alive-interval: func
self
: borrow<tcp-socket
>value
: duration
error-code
>[method]tcp-socket.keep-alive-count: func
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.
+invalid-argument
: (set) The provided value was 0.self
: borrow<tcp-socket
>bool
, error-code
>u32
, error-code
>[method]tcp-socket.set-keep-alive: func
[method]tcp-socket.set-keep-alive-count: func
self
: borrow<tcp-socket
>value
: bool
self
: borrow<tcp-socket
>value
: u32
error-code
>error-code
>[method]tcp-socket.unicast-hop-limit: func
[method]tcp-socket.hop-limit: func
Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+If the provided value is 0, an invalid-argument
error is returned.
invalid-argument
: (set) The TTL value must be 1 or higher.address
is unspecified.
self
: borrow<tcp-socket
>self
: borrow<tcp-socket
>u8
, error-code
>u8
, error-code
>[method]tcp-socket.set-unicast-hop-limit: func
[method]tcp-socket.set-hop-limit: func
self
: borrow<tcp-socket
>value
: u8
self
: borrow<tcp-socket
>value
: u8
error-code
>error-code
>[method]tcp-socket.receive-buffer-size: func
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.
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.output-stream
associ
error-code
>type network
tcp-socket
>, error-code
>type pollable