wasi:clocks/wall-clock@0.2.0-rc-2023-11-10wasi:io/poll@0.2.0-rc-2023-11-10wasi:clocks/monotonic-clock@0.2.0-rc-2023-11-10wasi:cli/environment@0.2.0-rc-2023-11-10wasi:cli/exit@0.2.0-rc-2023-11-10wasi:io/error@0.2.0-rc-2023-11-10wasi:io/poll@0.2.0-rc-2023-11-10wasi:io/streams@0.2.0-rc-2023-11-10wasi:cli/stdin@0.2.0-rc-2023-11-10wasi:cli/stdout@0.2.0-rc-2023-11-10wasi:cli/stderr@0.2.0-rc-2023-11-10wasi:cli/terminal-input@0.2.0-rc-2023-11-10wasi:cli/terminal-output@0.2.0-rc-2023-11-10wasi:cli/terminal-stdin@0.2.0-rc-2023-11-10wasi:cli/terminal-stdout@0.2.0-rc-2023-11-10wasi:cli/terminal-stderr@0.2.0-rc-2023-11-10wasi:clocks/monotonic-clock@0.2.0-rc-2023-11-10wasi:clocks/wall-clock@0.2.0-rc-2023-11-10wasi:filesystem/types@0.2.0-rc-2023-11-10wasi:filesystem/preopens@0.2.0-rc-2023-11-10wasi:sockets/network@0.2.0-rc-2023-11-10wasi:sockets/instance-network@0.2.0-rc-2023-11-10wasi:sockets/ip-name-lookup@0.2.0-rc-2023-11-10wasi:sockets/tcp@0.2.0-rc-2023-11-10wasi:sockets/tcp-create-socket@0.2.0-rc-2023-11-10wasi:sockets/udp@0.2.0-rc-2023-11-10wasi:sockets/udp-create-socket@0.2.0-rc-2023-11-10wasi:sockets/tcp@0.2.0-rc-2023-11-10wasi:sockets/tcp-create-socket@0.2.0-rc-2023-11-10wasi:sockets/ip-name-lookup@0.2.0-rc-2023-11-10wasi:random/random@0.2.0-rc-2023-11-10wasi:random/insecure@0.2.0-rc-2023-11-10wasi:random/insecure-seed@0.2.0-rc-2023-11-10wasi:cli/environment@0.2.0-rc-2023-11-10wasi:cli/exit@0.2.0-rc-2023-11-10wasi:cli/stdin@0.2.0-rc-2023-11-10wasi:cli/stdout@0.2.0-rc-2023-11-10wasi:cli/stderr@0.2.0-rc-2023-11-10wasi:cli/terminal-input@0.2.0-rc-2023-11-10wasi:cli/terminal-output@0.2.0-rc-2023-11-10wasi:cli/terminal-stdin@0.2.0-rc-2023-11-10wasi:cli/terminal-stdout@0.2.0-rc-2023-11-10wasi:cli/terminal-stderr@0.2.0-rc-2023-11-10WASI 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.
+record datetimeA time and date in seconds plus nanoseconds.
-get-environment: funcGet the POSIX-style environment variables.
+Each environment variable is provided as a pair of string variable names +and string value.
+Morally, these are a value import, but until value imports are available +in the component model, this import function should return the same +values each time it is called.
+seconds: u64nanoseconds: u32string, string)>get-arguments: funcGet the POSIX-style arguments to the program.
+initial-cwd: funcReturn a path that programs should use as their initial current working
+directory, interpreting . as shorthand for this.
now: funcRead 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.
-exit: funcExit the current instance and any linked instances.
+resource errorA 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, errors 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<error> and returns
+option<wasi:filesystem/types/error-code>.
error into a more
+concrete type is open.[method]error.to-debug-string: funcReturns 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.
+resolution: funcQuery the resolution of the clock.
-The nanoseconds field of the output is always less than 1000000000.
datetimestringA poll API intended to let users wait for I/O events on multiple handles @@ -84,7 +114,7 @@ at once.
resource pollablepollable represents a single I/O event which may be ready, or not.[method]pollable.ready: funcReturn the readiness of a pollable. This function never blocks.
@@ -128,88 +158,6 @@ being reaedy for I/O. -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 durationu64
A duration of time, in nanoseconds. -
now: funcRead the current value of the clock.
-The clock is monotonic, therefore calling this function repeatedly will -produce a sequence of non-decreasing values.
-instantresolution: funcQuery the resolution of the clock. Returns the duration of time -corresponding to a clock tick.
-durationsubscribe-instant: funcCreate a pollable which will resolve once the specified instant
-occured.
pollable>subscribe-duration: funcCreate a pollable which will resolve once the given duration has
-elapsed, starting at the time at which this function was called.
-occured.
pollable>resource error[method]error.to-debug-string: funcReturns 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.
@@ -240,8 +188,21 @@ future operations.resource input-streamAn input bytestream.
+input-streams are non-blocking to the extent practical on underlying
+platforms. I/O operations always return promptly; if fewer bytes are
+promptly available than requested, they return the number of bytes promptly
+available, which could even be zero. To wait for data to be available,
+use the subscribe function to obtain a pollable which can be polled
+for using wasi:io/poll.
resource output-streamAn output bytestream.
+output-streams are non-blocking to the extent practical on
+underlying platforms. Except where specified otherwise, I/O operations also
+always return promptly, after the number of bytes that can be written
+promptly, which could even be zero. To wait for the stream to be ready to
+accept data, the subscribe function to obtain a pollable which can be
+polled for using wasi:io/poll.[method]input-stream.read: funcPerform a non-blocking read from the stream.
@@ -362,7 +323,7 @@ following pseudo-code:let pollable = this.subscribe();
while !contents.is_empty() {
// Wait for the stream to become writable
- poll-one(pollable);
+ pollable.block();
let Ok(n) = this.check-write(); // eliding error handling
let len = min(n, contents.len());
let (chunk, rest) = contents.split_at(len);
@@ -371,7 +332,7 @@ while !contents.is_empty() {
}
this.flush();
// Wait for completion of `flush`
-poll-one(pollable);
+pollable.block();
// Check for any errors that arose during `flush`
let _ = this.check-write(); // eliding error handling
pollables created with this fun
[method]output-stream.write-zeroes: funcWrite zeroes to a stream.
-this should be used precisely like write with the exact same
+
This should be used precisely like write with the exact same
preconditions (must use check-write first), but instead of
passing a list of bytes, you simply pass the number of zero-bytes
that should be written.
let pollable = this.subscribe();
while num_zeroes != 0 {
// Wait for the stream to become writable
- poll-one(pollable);
+ pollable.block();
let Ok(n) = this.check-write(); // eliding error handling
let len = min(n, num_zeroes);
this.write-zeroes(len); // eliding error handling
@@ -462,7 +423,7 @@ while num_zeroes != 0 {
}
this.flush();
// Wait for completion of `flush`
-poll-one(pollable);
+pollable.block();
// Check for any errors that arose during `flush`
let _ = this.check-write(); // eliding error handling
splice.
u64, stream-error>WASI filesystem is a filesystem API primarily intended to let users run WASI -programs that access their files on their existing filesystems, without -significant overhead.
-It is intended to be roughly portable between Unix-family platforms and -Windows, though it does not hide many of the major differences.
-Paths are passed as interface-type strings, meaning they must consist of
-a sequence of Unicode Scalar Values (USVs). Some filesystems may contain
-paths which are not accessible by this API.
The directory separator in WASI is always the forward-slash (/).
All paths in WASI are relative paths, and are interpreted relative to a
-descriptor referring to a base directory. If a path argument to any WASI
-function starts with /, or if any step of resolving a path, including
-.. and symbolic link steps, reaches a directory outside of the base
-directory, or reaches a symlink to an absolute or rooted path in the
-underlying filesystem, the function fails with error-code::not-permitted.
For more information about WASI path resolution and sandboxing, see -WASI filesystem path resolution.
+type input-stream-#### `type output-stream` -[`output-stream`](#output_stream) -
-#### `type error` -[`error`](#error) +---- +
get-stdin: funcinput-stream>type output-stream-#### `type datetime` -[`datetime`](#datetime) +---- +
get-stdout: funcoutput-stream>type output-stream-#### `type filesize` -`u64` -
File size or length of a region within a file. -
enum descriptor-typeThe type of a filesystem object referenced by a descriptor.
-Note: This was called filetype in earlier versions of WASI.
get-stderr: funcoutput-stream>resource terminal-inputThe input side of a terminal.
+resource terminal-outputThe output side of a terminal.
+An interface providing an optional terminal-input for stdin as a
+link-time authority.
type terminal-input+---- +
get-terminal-stdin: funcIf stdin is connected to a terminal, return a terminal-input handle
+allowing further interaction with it.
terminal-input>>An interface providing an optional terminal-output for stdout as a
+link-time authority.
type terminal-output+---- +
get-terminal-stdout: funcIf stdout is connected to a terminal, return a terminal-output handle
+allowing further interaction with it.
terminal-output>>An interface providing an optional terminal-output for stderr as a
+link-time authority.
type terminal-output+---- +
get-terminal-stderr: funcIf stderr is connected to a terminal, return a terminal-output handle
+allowing further interaction with it.
terminal-output>>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 durationu64
A duration of time, in nanoseconds. +
now: funcRead the current value of the clock.
+The clock is monotonic, therefore calling this function repeatedly will +produce a sequence of non-decreasing values.
+instantresolution: funcQuery the resolution of the clock. Returns the duration of time +corresponding to a clock tick.
+durationsubscribe-instant: funcCreate a pollable which will resolve once the specified instant
+occured.
pollable>subscribe-duration: funcCreate a pollable which will resolve once the given duration has
+elapsed, starting at the time at which this function was called.
+occured.
pollable>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.
+record datetimeA time and date in seconds plus nanoseconds.
+seconds: u64nanoseconds: u32now: funcRead 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.
+datetimeresolution: funcQuery the resolution of the clock.
+The nanoseconds field of the output is always less than 1000000000.
+datetimeWASI filesystem is a filesystem API primarily intended to let users run WASI +programs that access their files on their existing filesystems, without +significant overhead.
+It is intended to be roughly portable between Unix-family platforms and +Windows, though it does not hide many of the major differences.
+Paths are passed as interface-type strings, meaning they must consist of
+a sequence of Unicode Scalar Values (USVs). Some filesystems may contain
+paths which are not accessible by this API.
The directory separator in WASI is always the forward-slash (/).
All paths in WASI are relative paths, and are interpreted relative to a
+descriptor referring to a base directory. If a path argument to any WASI
+function starts with /, or if any step of resolving a path, including
+.. and symbolic link steps, reaches a directory outside of the base
+directory, or reaches a symlink to an absolute or rooted path in the
+underlying filesystem, the function fails with error-code::not-permitted.
For more information about WASI path resolution and sandboxing, see +WASI filesystem path resolution.
+type input-stream+#### `type output-stream` +[`output-stream`](#output_stream) +
+#### `type error` +[`error`](#error) +
+#### `type datetime` +[`datetime`](#datetime) +
+#### `type filesize` +`u64` +
File size or length of a region within a file. +
enum descriptor-typeThe type of a filesystem object referenced by a descriptor.
+Note: This was called filetype in earlier versions of WASI.
The type of the descriptor or file is unknown or is different from any of the other types specified.
resource descriptorA descriptor is a reference to a filesystem object, which may be a file, +directory, named pipe, special file, or other object on which filesystem +calls may be made.
resource directory-entry-stream[method]descriptor.read-via-stream: funcReturn a stream for reading from a file, if available.
@@ -1408,6 +1574,9 @@ errors are filesystem-related errors.resource networkAn opaque resource that represents access to (a subset of) the network. +This enables context-based security for networking. +There is no need for this to map 1:1 to a physical network interface.
enum error-codeError codes.
In theory, every API can return any error code. @@ -1589,7 +1758,7 @@ combined with a couple of errors that are always possible:
network>type pollable-#### `type ip-address` -[`ip-address`](#ip_address) +#### `type ip-socket-address` +[`ip-socket-address`](#ip_socket_address)
-#### `resource resolve-address-stream` -
resolve-addresses: funcResolve 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.
-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-argument: name is a syntactically invalid domain name or IP address.+#### `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-datagramA datagram to be sent out.
+resolve-address-stream>, error-code>[method]resolve-address-stream.resolve-next-address: funcReturns 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.
-name-unresolvable: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)temporary-resolver-failure: A temporary failure in name resolution occurred. (EAI_AGAIN)permanent-resolver-failure: A permanent failure in name resolution occurred. (EAI_FAIL)would-block: A result is not available yet. (EWOULDBLOCK, EAGAIN)self: borrow<resolve-address-stream>ip-address>, error-code>[method]resolve-address-stream.subscribe: funcCreate 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.
self: borrow<resolve-address-stream>pollable>type input-stream-#### `type output-stream` -[`output-stream`](#output_stream) -
-#### `type pollable` -[`pollable`](#pollable) -
-#### `type duration` -[`duration`](#duration) -
-#### `type network` -[`network`](#network) -
-#### `type error-code` -[`error-code`](#error_code) -
-#### `type ip-socket-address` -[`ip-socket-address`](#ip_socket_address) -
-#### `type ip-address-family` -[`ip-address-family`](#ip_address_family) -
-#### `enum shutdown-type` -
Similar to `SHUT_RD` in POSIX. -
Similar to `SHUT_WR` in POSIX. +
data: list<u8>
The payload.
Similar to `SHUT_RDWR` in POSIX. +
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 tcp-socketresource udp-socketA UDP socket handle.
+resource incoming-datagram-streamresource outgoing-datagram-stream[method]tcp-socket.start-bind: func[method]udp-socket.start-bind: funcBind 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 a listen or connect operation 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 errorsinvalid-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 errorsself: borrow<tcp-socket>network: borrow<network>local-address: ip-socket-addressself: borrow<udp-socket>network: borrow<network>local-address: ip-socket-addresserror-code>error-code>[method]tcp-socket.finish-bind: func[method]udp-socket.finish-bind: funcself: borrow<tcp-socket>self: borrow<udp-socket>error-code>[method]tcp-socket.start-connect: funcConnect to a remote endpoint.
-On success:
-error-code>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:
+[method]udp-socket.stream: funcSet 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:
connect fails because an input/state validation error, the socket should remain usable.drop, any method after such a failure may return an error.send can only be used to send to this destination.receive will only return datagrams sent from the provided remote-address.start errorsThis 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.
+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)connection-aborted: The connection was aborted. (ECONNABORTED)remote-unreachable: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)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)not-in-progress: A connect operation is not in progress.would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)connection-refused: The connection was refused. (ECONNREFUSED)drop, any method after such a failure may return an error.<
self: borrow<tcp-socket>network: borrow<network>remote-address: ip-socket-addressself: borrow<udp-socket>remote-address: option<ip-socket-address>error-code>incoming-datagram-stream>, own<outgoing-datagram-stream>), error-code>[method]tcp-socket.finish-connect: func[method]udp-socket.local-address: funcGet 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
+addressis unspecified.
WASI is stricter and requires local-address to return invalid-state when the socket hasn't been bound yet.
self: borrow<tcp-socket>invalid-state: The socket is not bound to any local address.input-stream>, own<output-stream>), error-code>[method]tcp-socket.start-listen: funcStart listening for new connections.
-Transitions the socket into the Listener state.
-Unlike POSIX:
+self: borrow<udp-socket>start errorsinvalid-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.ip-socket-address, error-code>finish errors[method]udp-socket.remote-address: funcGet the address the socket is currently streaming to.
+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)invalid-state: The socket is not streaming to a specific remote address. (ENOTCONN)self: borrow<tcp-socket>self: borrow<udp-socket>error-code>ip-socket-address, error-code>[method]tcp-socket.finish-listen: func[method]udp-socket.address-family: funcWhether this is a IPv4 or IPv6 socket.
+Equivalent to the SO_DOMAIN socket option.
self: borrow<tcp-socket>self: borrow<udp-socket>error-code>ip-address-family[method]tcp-socket.accept: funcAccept a new client socket.
-The returned socket is bound and in the Connection state. The following properties are inherited from the listener socket:
+[method]udp-socket.ipv6-only: funcWhether IPv4 compatibility (dual-stack) mode is disabled or not.
+Equivalent to the IPV6_V6ONLY socket option.
+address-familyipv6-onlykeep-alive-enabledkeep-alive-idle-timekeep-alive-intervalkeep-alive-counthop-limitreceive-buffer-sizesend-buffer-sizenot-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.)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.
-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)self: borrow<udp-socket>bool, error-code>[method]udp-socket.set-ipv6-only: funcself: borrow<tcp-socket>self: borrow<udp-socket>value: booltcp-socket>, own<input-stream>, own<output-stream>), error-code>error-code>[method]tcp-socket.local-address: funcGet 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
-addressis unspecified.
WASI is stricter and requires local-address to return invalid-state when the socket hasn't been bound yet.
[method]udp-socket.unicast-hop-limit: funcEquivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+If the provided value is 0, an invalid-argument error is returned.
invalid-state: The socket is not bound to any local address.invalid-argument: (set) The TTL value must be 1 or higher.self: borrow<udp-socket>u8, error-code>[method]udp-socket.set-unicast-hop-limit: funcself: borrow<tcp-socket>self: borrow<udp-socket>value: u8ip-socket-address, error-code>error-code>[method]tcp-socket.remote-address: funcGet the remote address.
+[method]udp-socket.receive-buffer-size: funcThe kernel buffer space reserved for sends/receives on this socket.
+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-state: The socket is not connected to a remote address. (ENOTCONN)invalid-argument: (set) The provided value was 0.self: borrow<tcp-socket>self: borrow<udp-socket>ip-socket-address, error-code>u64, error-code>[method]tcp-socket.is-listening: funcWhether the socket is listening for new connections.
-Equivalent to the SO_ACCEPTCONN socket option.
+[method]udp-socket.set-receive-buffer-size: funcself: borrow<tcp-socket>self: borrow<udp-socket>value: u64boolerror-code>[method]tcp-socket.address-family: funcWhether this is a IPv4 or IPv6 socket.
-Equivalent to the SO_DOMAIN socket option.
+[method]udp-socket.send-buffer-size: funcself: borrow<tcp-socket>self: borrow<udp-socket>[method]tcp-socket.ipv6-only: funcWhether IPv4 compatibility (dual-stack) mode is disabled or not.
-Equivalent to the IPV6_V6ONLY socket option.
-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.)u64, error-code>[method]udp-socket.set-send-buffer-size: funcself: borrow<tcp-socket>self: borrow<udp-socket>value: u64bool, error-code>error-code>[method]tcp-socket.set-ipv6-only: func[method]udp-socket.subscribe: funcCreate 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.
self: borrow<tcp-socket>value: boolself: borrow<udp-socket>error-code>pollable>[method]incoming-datagram-stream.receive: funcReceive 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).[method]tcp-socket.set-listen-backlog-size: funcHints 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.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<tcp-socket>value: u64error-code>self: borrow<incoming-datagram-stream>max-results: u64[method]tcp-socket.keep-alive-enabled: funcEnables 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.incoming-datagram>, error-code>Equivalent to the SO_KEEPALIVE socket option.
+[method]incoming-datagram-stream.subscribe: funcCreate 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<tcp-socket>self: borrow<incoming-datagram-stream>bool, error-code>pollable>[method]tcp-socket.set-keep-alive-enabled: func[method]outgoing-datagram-stream.check-send: funcCheck 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<tcp-socket>value: boolself: borrow<outgoing-datagram-stream>error-code>u64, error-code>[method]tcp-socket.keep-alive-idle-time: funcAmount 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)
+[method]outgoing-datagram-stream.send: funcSend 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: (set) The provided value was 0.self: borrow<tcp-socket>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)duration, error-code>[method]tcp-socket.set-keep-alive-idle-time: funcself: borrow<tcp-socket>value: durationself: borrow<outgoing-datagram-stream>datagrams: list<outgoing-datagram>error-code>[method]tcp-socket.keep-alive-interval: funcThe 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.u64, error-code>[method]outgoing-datagram-stream.subscribe: funcCreate 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<tcp-socket>self: borrow<outgoing-datagram-stream>duration, error-code>pollable>[method]tcp-socket.set-keep-alive-interval: funcself: borrow<tcp-socket>value: durationerror-code>[method]tcp-socket.keep-alive-count: funcThe 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>u32, error-code>[method]tcp-socket.set-keep-alive-count: funcself: borrow<tcp-socket>value: u32error-code>[method]tcp-socket.hop-limit: funcEquivalent 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.invalid-state: (set) The socket is already in the Connection state.invalid-state: (set) The socket is already in the Listener state.self: borrow<tcp-socket>u8, error-code>[method]tcp-socket.set-hop-limit: funcself: borrow<tcp-socket>value: u8error-code>[method]tcp-socket.receive-buffer-size: funcThe kernel buffer space reserved for sends/receives on this socket.
-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.self: borrow<tcp-socket>u64, error-code>[method]tcp-socket.set-receive-buffer-size: funcself: borrow<tcp-socket>value: u64error-code>[method]tcp-socket.send-buffer-size: funcself: borrow<tcp-socket>u64, error-code>[method]tcp-socket.set-send-buffer-size: funcself: borrow<tcp-socket>value: u64error-code>[method]tcp-socket.subscribe: funcCreate 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.
self: borrow<tcp-socket>pollable>[method]tcp-socket.shutdown: funcInitiate a graceful shutdown.
-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.output-stream associated with this socket will return an error.The shutdown function does not close (drop) the socket.
-invalid-state: The socket is not in the Connection state. (ENOTCONN)self: borrow<tcp-socket>shutdown-type: shutdown-typeerror-code>type networkoutput-stream associ
#### `type ip-address-family`
[`ip-address-family`](#ip_address_family)
-#### `type tcp-socket` -[`tcp-socket`](#tcp_socket) +#### `type udp-socket` +[`udp-socket`](#udp_socket)
----
create-tcp-socket: funcCreate a new TCP socket.
-Similar to socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP) in POSIX.
create-udp-socket: funcCreate 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/listen/connect
-is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world.
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 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)tcp-socket>, error-code>udp-socket>, error-code>type pollabletype input-stream+#### `type output-stream` +[`output-stream`](#output_stream) +
+#### `type pollable` +[`pollable`](#pollable) +
+#### `type duration` +[`duration`](#duration)
#### `type network` [`network`](#network) @@ -2322,55 +2271,38 @@ is called, the socket is effectively an in-memory configuration object, unable t #### `type ip-address-family` [`ip-address-family`](#ip_address_family)
-#### `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.
Similar to `SHUT_RD` in POSIX.
record outgoing-datagramA datagram to be sent out.
-data: list<u8>
The payload. +
+Similar to `SHUT_WR` in POSIX.
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.
Similar to `SHUT_RDWR` in POSIX.
resource udp-socketresource incoming-datagram-streamresource outgoing-datagram-streamresource tcp-socket[method]udp-socket.start-bind: func[method]tcp-socket.start-bind: funcBind 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 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.
start errorsinvalid-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 errorsself: borrow<udp-socket>network: borrow<network>local-address: ip-socket-addressself: borrow<tcp-socket>network: borrow<network>local-address: ip-socket-addresserror-code>error-code>[method]udp-socket.finish-bind: func[method]tcp-socket.finish-bind: funcself: borrow<udp-socket>self: borrow<tcp-socket>error-code>error-code>[method]udp-socket.stream: funcSet 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:
[method]tcp-socket.start-connect: funcConnect to a remote endpoint.
+On success:
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.
-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 errorsinvalid-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 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)invalid-argument: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)invalid-state: The socket is not bound.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)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)remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)connection-refused: The connection was refused. (ECONNREFUSED)not-in-progress: A connect operation is not in progress.would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)self: borrow<udp-socket>remote-address: option<ip-socket-address>self: borrow<tcp-socket>network: borrow<network>remote-address: ip-socket-addressincoming-datagram-stream>, own<outgoing-datagram-stream>), error-code>error-code>[method]udp-socket.local-address: funcGet the current bound address.
+[method]tcp-socket.finish-connect: funcself: borrow<tcp-socket>input-stream>, own<output-stream>), error-code>[method]tcp-socket.start-listen: funcStart listening for new connections.
+Transitions the socket into the Listener state.
+Unlike POSIX:
+start errorsinvalid-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 errorsaddress-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)self: borrow<tcp-socket>error-code>[method]tcp-socket.finish-listen: funcself: borrow<tcp-socket>error-code>[method]tcp-socket.accept: funcAccept a new client socket.
+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-sizeOn 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.
+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)self: borrow<tcp-socket>tcp-socket>, own<input-stream>, own<output-stream>), error-code>[method]tcp-socket.local-address: funcGet the bound local address.
POSIX mentions:
If the socket has not been bound to a local name, the value @@ -2470,282 +2502,340 @@ stored in the object pointed to by
addressis unspecified.References
-
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html
-- https://man7.org/linux/man-pages/man2/getsockname.2.html
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname
-- https://man.freebsd.org/cgi/man.cgi?getsockname
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html
+- https://man7.org/linux/man-pages/man2/getsockname.2.html
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname
+- https://man.freebsd.org/cgi/man.cgi?getsockname
+Params
++
+- +
self: borrow<tcp-socket>Return values
++
+- result<
+ip-socket-address,error-code>+
[method]tcp-socket.remote-address: funcGet the remote address.
+Typical errors
++
+- +
invalid-state: The socket is not connected to a remote address. (ENOTCONN)References
++
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html
+- https://man7.org/linux/man-pages/man2/getpeername.2.html
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername
+- https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1
+Params
++
+- +
self: borrow<tcp-socket>Return values
++
+- result<
+ip-socket-address,error-code>+
[method]tcp-socket.is-listening: funcWhether the socket is listening for new connections.
+Equivalent to the SO_ACCEPTCONN socket option.
+Params
++
+- +
self: borrow<tcp-socket>Return values
+ ++
[method]tcp-socket.address-family: funcWhether this is a IPv4 or IPv6 socket.
+Equivalent to the SO_DOMAIN socket option.
+Params
++
+- +
self: borrow<tcp-socket>Return values
+ ++
[method]tcp-socket.ipv6-only: funcWhether IPv4 compatibility (dual-stack) mode is disabled or not.
+Equivalent to the IPV6_V6ONLY socket option.
+Typical errors
++
+- +
invalid-state: (set) The socket is already bound.- +
not-supported: (get/set)thissocket is an IPv4 socket.- +
not-supported: (set) Host does not support dual-stack sockets. (Implementations are not required to.)Params
++
+- +
self: borrow<tcp-socket>Return values
++
+- result<
+bool,error-code>+
[method]tcp-socket.set-ipv6-only: funcParams
++
+- +
self: borrow<tcp-socket>- +
value:boolReturn values
++
+- result<_,
+error-code>+
[method]tcp-socket.set-listen-backlog-size: funcHints the desired listen queue size. Implementations are free to ignore this.
+If the provided value is 0, an
+invalid-argumenterror is returned. +Any other value will never cause an error, but it might be silently clamped and/or rounded.Typical errors
++
- +
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
-
- +
self: borrow<udp-socket>- +
self: borrow<tcp-socket>value:u64Return values
-
-- result<
-ip-socket-address,error-code>-
[method]udp-socket.remote-address: funcGet the address the socket is currently streaming to.
-Typical errors
--
-- +
invalid-state: The socket is not streaming to a specific remote address. (ENOTCONN)- result<_,
error-code>References
++
[method]tcp-socket.keep-alive-enabled: funcEnables or disables keepalive.
+The keepalive behavior can be adjusted using:
-
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html
-- https://man7.org/linux/man-pages/man2/getpeername.2.html
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername
-- https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1
+- +
keep-alive-idle-time- +
keep-alive-intervalkeep-alive-count+These properties can be configured whilekeep-alive-enabledis false, but only come into effect whenkeep-alive-enabledis true.Equivalent to the SO_KEEPALIVE socket option.
Params
-
- +
self: borrow<udp-socket>self: borrow<tcp-socket>Return values
-
-- result<
+ip-socket-address,error-code>- result<
bool,error-code>-
[method]udp-socket.address-family: funcWhether this is a IPv4 or IPv6 socket.
-Equivalent to the SO_DOMAIN socket option.
+
[method]tcp-socket.set-keep-alive-enabled: funcParams
-
- +
self: borrow<udp-socket>- +
self: borrow<tcp-socket>value:boolReturn values
-
-- +
ip-address-family- result<_,
error-code>-
[method]udp-socket.ipv6-only: funcWhether IPv4 compatibility (dual-stack) mode is disabled or not.
-Equivalent to the IPV6_V6ONLY socket option.
++
[method]tcp-socket.keep-alive-idle-time: funcAmount of time the connection has to be idle before TCP starts sending keepalive packets.
+If the provided value is 0, an
+invalid-argumenterror 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
-
- -
not-supported: (get/set)thissocket 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.)invalid-argument: (set) The provided value was 0.Params
-
- +
self: borrow<udp-socket>self: borrow<tcp-socket>Return values
-
-- result<
+bool,error-code>- result<
duration,error-code>+
[method]udp-socket.set-ipv6-only: func
[method]tcp-socket.set-keep-alive-idle-time: funcParams
-
- -
self: borrow<udp-socket>- +
value:bool- +
self: borrow<tcp-socket>value:durationReturn values
-
-- result<_,
+error-code>- result<_,
error-code>-
[method]udp-socket.unicast-hop-limit: funcEquivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
-If the provided value is 0, an
+invalid-argumenterror is returned.+
[method]tcp-socket.keep-alive-interval: funcThe time between keepalive packets.
+If the provided value is 0, an
+invalid-argumenterror 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
-
- +
invalid-argument: (set) The TTL value must be 1 or higher.invalid-argument: (set) The provided value was 0.Params
-
- +
self: borrow<udp-socket>self: borrow<tcp-socket>Return values
-
-- result<
+u8,error-code>- result<
duration,error-code>+
[method]udp-socket.set-unicast-hop-limit: func
[method]tcp-socket.set-keep-alive-interval: funcParams
-
- -
self: borrow<udp-socket>- +
value:u8- +
self: borrow<tcp-socket>value:durationReturn values
-
-- result<_,
+error-code>- result<_,
error-code>-
[method]udp-socket.receive-buffer-size: funcThe kernel buffer space reserved for sends/receives on this socket.
++
[method]tcp-socket.keep-alive-count: funcThe maximum amount of keepalive packets TCP should send before aborting the connection.
If the provided value is 0, an
-invalid-argumenterror 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.
+Equivalent to the TCP_KEEPCNT socket option.
Typical errors
invalid-argument: (set) The provided value was 0.Params
-
- +
self: borrow<udp-socket>self: borrow<tcp-socket>Return values
-
-- result<
+u64,error-code>- result<
u32,error-code>+
[method]udp-socket.set-receive-buffer-size: func
[method]tcp-socket.set-keep-alive-count: funcParams
-
- -
self: borrow<udp-socket>- +
value:u64- +
self: borrow<tcp-socket>value:u32Return values
-
-- result<_,
-error-code>-
[method]udp-socket.send-buffer-size: funcParams
--
-- +
self: borrow<udp-socket>- result<_,
error-code>Return values
++
[method]tcp-socket.hop-limit: funcEquivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+If the provided value is 0, an
+invalid-argumenterror is returned.Typical errors
-
-- result<
+u64,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.
[method]udp-socket.set-send-buffer-size: funcParams
-
- -
self: borrow<udp-socket>- +
value:u64self: borrow<tcp-socket>Return values
-
-- result<_,
+error-code>- result<
u8,error-code>-
[method]udp-socket.subscribe: funcCreate a
-pollablewhich 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
+futureis natively supported in Preview3.
[method]tcp-socket.set-hop-limit: funcParams
-
- +
self: borrow<udp-socket>- +
self: borrow<tcp-socket>value:u8Return values
-
-- own<
+pollable>- result<_,
error-code>-
[method]incoming-datagram-stream.receive: funcReceive messages on the socket.
-This function attempts to receive up to
-max-resultsdatagrams 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:
++
[method]tcp-socket.receive-buffer-size: funcThe kernel buffer space reserved for sends/receives on this socket.
+If the provided value is 0, an
+invalid-argumenterror 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
-
-- -
max-resultsis 0, or:- +
max-resultsis greater than 0, but no results are immediately available. -This function never returnserror(would-block).- +
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.Typical errors
+Params
-
-- -
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<tcp-socket>References
+Return values
-
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvfrom.html
-- https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvmsg.html
-- https://man7.org/linux/man-pages/man2/recv.2.html
-- https://man7.org/linux/man-pages/man2/recvmmsg.2.html
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recv
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recvfrom
-- https://learn.microsoft.com/en-us/previous-versions/windows/desktop/legacy/ms741687(v=vs.85)
-- https://man.freebsd.org/cgi/man.cgi?query=recv&sektion=2
+- result<
u64,error-code>
[method]tcp-socket.set-receive-buffer-size: funcParams
-
- -
self: borrow<incoming-datagram-stream>- +
max-results:u64- +
self: borrow<tcp-socket>value:u64Return values
-
-- result<list<
+incoming-datagram>,error-code>- result<_,
error-code>-
[method]incoming-datagram-stream.subscribe: funcCreate a
-pollablewhich 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
+futureis natively supported in Preview3.
[method]tcp-socket.send-buffer-size: funcParams
-
- +
self: borrow<incoming-datagram-stream>self: borrow<tcp-socket>Return values
-
-- own<
+pollable>- result<
u64,error-code>-
[method]outgoing-datagram-stream.check-send: funcCheck readiness for sending. This function never blocks.
-Returns the number of datagrams permitted for the next call to
-send, -or an error. Callingsendwith more datagrams than this function has -permitted will trap.When this function returns ok(0), the
-subscribepollable will -become ready when this function will report at least ok(1), or an -error.Never returns
+would-block.
[method]tcp-socket.set-send-buffer-size: funcParams
-
- +
self: borrow<outgoing-datagram-stream>- +
self: borrow<tcp-socket>value:u64Return values
-
-- result<
+u64,error-code>- result<_,
error-code>-
[method]outgoing-datagram-stream.send: funcSend messages on the socket.
-This function attempts to send all provided
-datagramson the socket without blocking and -returns how many messages were actually sent (or queued for sending). This function never -returnserror(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
-datagramslist 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
-sendmust be permitted by a precedingcheck-send. Implementations must trap if -eithercheck-sendwas not called ordatagramscontains more items thancheck-sendpermitted.Typical errors
++
[method]tcp-socket.subscribe: funcCreate a
+pollablewhich 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
+futureis natively supported in Preview3.Params
-
-- -
invalid-argument: Theremote-addresshas the wrong address family. (EAFNOSUPPORT)- -
invalid-argument:remote-addressis 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 inremote-addressis set to INADDR_ANY (0.0.0.0/::). (EDESTADDRREQ, EADDRNOTAVAIL)- -
invalid-argument: The port inremote-addressis set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)- -
invalid-argument: The socket is in "connected" mode andremote-addressissomevalue that does not match the address passed tostream. (EISCONN)- -
invalid-argument: The socket is not "connected" and no value forremote-addresswas 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<tcp-socket>References
+Return values
-
-- https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendto.html
-- https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendmsg.html
-- https://man7.org/linux/man-pages/man2/send.2.html
-- https://man7.org/linux/man-pages/man2/sendmmsg.2.html
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-send
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-sendto
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasendmsg
-- https://man.freebsd.org/cgi/man.cgi?query=send&sektion=2
+- own<
pollable>Params
++
[method]tcp-socket.shutdown: funcInitiate a graceful shutdown.
++
+- receive: the socket is not expecting to receive any more data from the peer. All subsequent read +operations on the
+input-streamassociated with this socket will return an End Of Stream indication. +Any data still in the receive queue at time of callingshutdownwill be discarded.- send: the socket is not expecting to send any more data to the peer. All subsequent write +operations on the
+output-streamassociated 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
-
-- -
self: borrow<outgoing-datagram-stream>- +
datagrams: list<outgoing-datagram>invalid-state: The socket is not in the Connection state. (ENOTCONN)Return values
+References
-
-- result<
+u64,error-code>- https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html
+- https://man7.org/linux/man-pages/man2/shutdown.2.html
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-shutdown
+- https://man.freebsd.org/cgi/man.cgi?query=shutdown&sektion=2
-
[method]outgoing-datagram-stream.subscribe: funcCreate a
-pollablewhich 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
futureis natively supported in Preview3.Params
-
- +
self: borrow<outgoing-datagram-stream>- +
self: borrow<tcp-socket>shutdown-type:shutdown-typeReturn values
-
-- own<
+pollable>- result<_,
error-code>Import interface wasi:sockets/udp-create-socket@0.2.0-rc-2023-11-10
+Import interface wasi:sockets/tcp-create-socket@0.2.0-rc-2023-11-10
Types
@@ -2757,24 +2847,24 @@ It's planned to be removed when
type networkfutureis natively supported in Pre #### `type ip-address-family` [`ip-address-family`](#ip_address_family)-#### `type udp-socket` -[`udp-socket`](#udp_socket) +#### `type tcp-socket` +[`tcp-socket`](#tcp_socket)
----
Functions
--
create-udp-socket: funcCreate a new UDP socket.
-Similar to
+socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP)in POSIX.+
create-tcp-socket: funcCreate 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
+at time of creation, the socket is not bound to anynetworkyet. Up to the momentbindis called, -the socket is effectively an in-memory configuration object, unable to communicate with the outside world.networkyet. Up to the momentbind/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 specifiedaddress-familyis not supported. (EAFNOSUPPORT)new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)References:
+References
- https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html
- https://man7.org/linux/man-pages/man2/socket.2.html
@@ -2783,11 +2873,91 @@ the socket is effectively an in-memory configuration object, unable to communicaParams
Return values
-
+- result<own<
+udp-socket>,error-code>- result<own<
+tcp-socket>,error-code>Import interface wasi:sockets/ip-name-lookup@0.2.0-rc-2023-11-10
+
+Types
++ +
type pollable+#### `type network` +[`network`](#network) +
+#### `type error-code` +[`error-code`](#error_code) +
+#### `type ip-address` +[`ip-address`](#ip_address) +
+#### `resource resolve-address-stream` +
+Functions
++
resolve-addresses: funcResolve 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.
+This function never blocks. It either immediately fails or immediately +returns successfully with a
+resolve-address-streamthat can be used +to (asynchronously) fetch the results.Typical errors
++
+- +
invalid-argument:nameis a syntactically invalid domain name or IP address.References:
++
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html
+- https://man7.org/linux/man-pages/man3/getaddrinfo.3.html
+- https://learn.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo
+- https://man.freebsd.org/cgi/man.cgi?query=getaddrinfo&sektion=3
+Params
+ +Return values
++
+- result<own<
+resolve-address-stream>,error-code>+
[method]resolve-address-stream.resolve-next-address: funcReturns the next address from the resolver.
+This function should be called multiple times. On each call, it will +return the next address in connection order preference. If all +addresses have been exhausted, this function returns
+none.This function never returns IPv4-mapped IPv6 addresses.
+Typical errors
++
+- +
name-unresolvable: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)- +
temporary-resolver-failure: A temporary failure in name resolution occurred. (EAI_AGAIN)- +
permanent-resolver-failure: A permanent failure in name resolution occurred. (EAI_FAIL)- +
would-block: A result is not available yet. (EWOULDBLOCK, EAGAIN)Params
++
+- +
self: borrow<resolve-address-stream>Return values
++
+- result<option<
+ip-address>,error-code>+
[method]resolve-address-stream.subscribe: funcCreate a
+pollablewhich 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
+futureis natively supported in Preview3.Params
++
+- +
self: borrow<resolve-address-stream>Return values
++
- own<
pollable>Import interface wasi:random/random@0.2.0-rc-2023-11-10
WASI Random is a random data API.
@@ -2875,140 +3045,6 @@ protection. -Import interface wasi:cli/environment@0.2.0-rc-2023-11-10
-
-Functions
--
get-environment: funcGet the POSIX-style environment variables.
-Each environment variable is provided as a pair of string variable names -and string value.
-Morally, these are a value import, but until value imports are available -in the component model, this import function should return the same -values each time it is called.
-Return values
- --
get-arguments: funcGet the POSIX-style arguments to the program.
-Return values
- --
initial-cwd: funcReturn a path that programs should use as their initial current working -directory, interpreting
-.as shorthand for this.Return values
- -Import interface wasi:cli/exit@0.2.0-rc-2023-11-10
-
-Functions
--
exit: funcExit the current instance and any linked instances.
-Params
--
-- -
status: resultImport interface wasi:cli/stdin@0.2.0-rc-2023-11-10
-
-Types
-- -
type input-stream----- -
Functions
--
get-stdin: funcReturn values
--
-- own<
-input-stream>Import interface wasi:cli/stdout@0.2.0-rc-2023-11-10
-
-Types
-- -
type output-stream----- -
Functions
--
get-stdout: funcReturn values
--
-- own<
-output-stream>Import interface wasi:cli/stderr@0.2.0-rc-2023-11-10
-
-Types
-- -
type output-stream----- -
Functions
--
get-stderr: funcReturn values
--
-- own<
-output-stream>Import interface wasi:cli/terminal-input@0.2.0-rc-2023-11-10
-
-Types
--
resource terminal-inputImport interface wasi:cli/terminal-output@0.2.0-rc-2023-11-10
-
-Types
--
resource terminal-outputImport interface wasi:cli/terminal-stdin@0.2.0-rc-2023-11-10
-An interface providing an optional
-terminal-inputfor stdin as a -link-time authority.
-Types
-- -
type terminal-input----- -
Functions
--
get-terminal-stdin: funcIf stdin is connected to a terminal, return a
-terminal-inputhandle -allowing further interaction with it.Return values
--
-- option<own<
-terminal-input>>Import interface wasi:cli/terminal-stdout@0.2.0-rc-2023-11-10
-An interface providing an optional
-terminal-outputfor stdout as a -link-time authority.
-Types
-- -
type terminal-output----- -
Functions
--
get-terminal-stdout: funcIf stdout is connected to a terminal, return a
-terminal-outputhandle -allowing further interaction with it.Return values
--
-- option<own<
-terminal-output>>Import interface wasi:cli/terminal-stderr@0.2.0-rc-2023-11-10
-An interface providing an optional
-terminal-outputfor stderr as a -link-time authority.
-Types
-- -
type terminal-output----- -
Functions
--
get-terminal-stderr: funcIf stderr is connected to a terminal, return a
-terminal-outputhandle -allowing further interaction with it.Return values
--
- option<own<
-terminal-output>>Export interface wasi:cli/run@0.2.0-rc-2023-11-10
Functions
diff --git a/reactor.md b/imports.md similarity index 98% rename from reactor.md rename to imports.md index 1115e35..74a7c7a 100644 --- a/reactor.md +++ b/imports.md @@ -1,77 +1,107 @@ -World reactor
+World imports
-
- Imports:
-
- interface
-wasi:clocks/wall-clock@0.2.0-rc-2023-11-10- interface
-wasi:io/poll@0.2.0-rc-2023-11-10- interface
+wasi:clocks/monotonic-clock@0.2.0-rc-2023-11-10- interface
+wasi:cli/environment@0.2.0-rc-2023-11-10- interface
wasi:cli/exit@0.2.0-rc-2023-11-10- interface
+wasi:io/error@0.2.0-rc-2023-11-10- interface
wasi:io/poll@0.2.0-rc-2023-11-10- interface
+wasi:io/streams@0.2.0-rc-2023-11-10- interface
+wasi:cli/stdin@0.2.0-rc-2023-11-10- interface
+wasi:cli/stdout@0.2.0-rc-2023-11-10- interface
+wasi:cli/stderr@0.2.0-rc-2023-11-10- interface
+wasi:cli/terminal-input@0.2.0-rc-2023-11-10- interface
+wasi:cli/terminal-output@0.2.0-rc-2023-11-10- interface
+wasi:cli/terminal-stdin@0.2.0-rc-2023-11-10- interface
+wasi:cli/terminal-stdout@0.2.0-rc-2023-11-10- interface
+wasi:cli/terminal-stderr@0.2.0-rc-2023-11-10- interface
+wasi:clocks/monotonic-clock@0.2.0-rc-2023-11-10- interface
wasi:clocks/wall-clock@0.2.0-rc-2023-11-10- interface
wasi:filesystem/types@0.2.0-rc-2023-11-10- interface
wasi:filesystem/preopens@0.2.0-rc-2023-11-10- interface
wasi:sockets/network@0.2.0-rc-2023-11-10- interface
-wasi:sockets/instance-network@0.2.0-rc-2023-11-10- interface
-wasi:sockets/ip-name-lookup@0.2.0-rc-2023-11-10- interface
-wasi:sockets/tcp@0.2.0-rc-2023-11-10- interface
wasi:sockets/tcp-create-socket@0.2.0-rc-2023-11-10- interface
wasi:sockets/udp@0.2.0-rc-2023-11-10- interface
+wasi:sockets/udp-create-socket@0.2.0-rc-2023-11-10- interface
+wasi:sockets/tcp@0.2.0-rc-2023-11-10- interface
+wasi:sockets/tcp-create-socket@0.2.0-rc-2023-11-10- interface
wasi:sockets/ip-name-lookup@0.2.0-rc-2023-11-10- interface
wasi:random/random@0.2.0-rc-2023-11-10- interface
wasi:random/insecure@0.2.0-rc-2023-11-10- interface
-wasi:random/insecure-seed@0.2.0-rc-2023-11-10- interface
-wasi:cli/environment@0.2.0-rc-2023-11-10- interface
-wasi:cli/exit@0.2.0-rc-2023-11-10- interface
-wasi:cli/stdin@0.2.0-rc-2023-11-10- interface
-wasi:cli/stdout@0.2.0-rc-2023-11-10- interface
-wasi:cli/stderr@0.2.0-rc-2023-11-10- interface
-wasi:cli/terminal-input@0.2.0-rc-2023-11-10- interface
-wasi:cli/terminal-output@0.2.0-rc-2023-11-10- interface
-wasi:cli/terminal-stdin@0.2.0-rc-2023-11-10- interface
-wasi:cli/terminal-stdout@0.2.0-rc-2023-11-10- interface
wasi:cli/terminal-stderr@0.2.0-rc-2023-11-10Import interface wasi:clocks/wall-clock@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.
+Import interface wasi:cli/environment@0.2.0-rc-2023-11-10
-Types
--
record datetimeA time and date in seconds plus nanoseconds.
-Record Fields
+Functions
++
get-environment: funcGet the POSIX-style environment variables.
+Each environment variable is provided as a pair of string variable names +and string value.
+Morally, these are a value import, but until value imports are available +in the component model, this import function should return the same +values each time it is called.
+Return values
-
+- -
seconds:u64- +
nanoseconds:u32- list<(
+string,string)>+
get-arguments: funcGet the POSIX-style arguments to the program.
+Return values
+ ++
initial-cwd: funcReturn a path that programs should use as their initial current working +directory, interpreting
+.as shorthand for this.Return values
+ +Import interface wasi:cli/exit@0.2.0-rc-2023-11-10
Functions
--
now: funcRead 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.
-Return values
++
exit: funcExit the current instance and any linked instances.
+Params
+Import interface wasi:io/error@0.2.0-rc-2023-11-10
+
+Types
++
resource errorA 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:iopackage, this resource is returned through the +wasi:io/streams/stream-errortype.To provide more specific error information, other interfaces may +provide functions to further "downcast" this error into more specific +error information. For example,
+errors 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<error>and returns +option<wasi:filesystem/types/error-code>.The set of functions which can "downcast" an
+errorinto a more +concrete type is open.Functions
++
[method]error.to-debug-string: funcReturns 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
+ --
resolution: funcQuery the resolution of the clock.
-The nanoseconds field of the output is always less than 1000000000.
Return values
-
- +
datetimestringImport interface wasi:io/poll@0.2.0-rc-2023-11-10
A poll API intended to let users wait for I/O events on multiple handles @@ -79,7 +109,7 @@ at once.
Types
-
resource pollable
+
pollablerepresents a single I/O event which may be ready, or not.Functions
[method]pollable.ready: funcReturn the readiness of a pollable. This function never blocks.
@@ -123,88 +153,6 @@ being reaedy for I/O. -Import interface wasi:clocks/monotonic-clock@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.
-
-Types
-- -
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-
u64A duration of time, in nanoseconds. -
-Functions
--
now: funcRead 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
--
-- -
instant-
resolution: funcQuery the resolution of the clock. Returns the duration of time -corresponding to a clock tick.
-Return values
--
-- -
duration-
subscribe-instant: funcCreate a
-pollablewhich will resolve once the specified instant -occured.Params
- -Return values
--
-- own<
-pollable>-
subscribe-duration: funcCreate a
-pollablewhich will resolve once the given duration has -elapsed, starting at the time at which this function was called. -occured.Params
- -Return values
--
-- own<
-pollable>Import interface wasi:io/error@0.2.0-rc-2023-11-10
-
-Types
--
resource error
-Functions
--
[method]error.to-debug-string: funcReturns 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
-Import interface wasi:io/streams@0.2.0-rc-2023-11-10
WASI I/O is an I/O abstraction API which is currently focused on providing stream types.
@@ -235,8 +183,21 @@ future operations.+
resource input-streamAn input bytestream.
+
input-streams are non-blocking to the extent practical on underlying +platforms. I/O operations always return promptly; if fewer bytes are +promptly available than requested, they return the number of bytes promptly +available, which could even be zero. To wait for data to be available, +use thesubscribefunction to obtain apollablewhich can be polled +for usingwasi:io/poll.-
resource output-stream
+An output bytestream.
+
output-streams are non-blocking to the extent practical on +underlying platforms. Except where specified otherwise, I/O operations also +always return promptly, after the number of bytes that can be written +promptly, which could even be zero. To wait for the stream to be ready to +accept data, thesubscribefunction to obtain apollablewhich can be +polled for usingwasi:io/poll.Functions
[method]input-stream.read: funcPerform a non-blocking read from the stream.
@@ -357,7 +318,7 @@ following pseudo-code:@@ -426,7 +387,7 @@ all derivedlet pollable = this.subscribe(); while !contents.is_empty() { // Wait for the stream to become writable - poll-one(pollable); + pollable.block(); let Ok(n) = this.check-write(); // eliding error handling let len = min(n, contents.len()); let (chunk, rest) = contents.split_at(len); @@ -366,7 +327,7 @@ while !contents.is_empty() { } this.flush(); // Wait for completion of `flush` -poll-one(pollable); +pollable.block(); // Check for any errors that arose during `flush` let _ = this.check-write(); // eliding error handlingpollables created with this fun
[method]output-stream.write-zeroes: funcWrite zeroes to a stream.
-this should be used precisely like
writewith the exact same +This should be used precisely like
@@ -449,7 +410,7 @@ the following pseudo-code:writewith the exact same preconditions (must use check-write first), but instead of passing a list of bytes, you simply pass the number of zero-bytes that should be written.@@ -508,48 +469,250 @@ is ready for reading, before performing thelet pollable = this.subscribe(); while num_zeroes != 0 { // Wait for the stream to become writable - poll-one(pollable); + pollable.block(); let Ok(n) = this.check-write(); // eliding error handling let len = min(n, num_zeroes); this.write-zeroes(len); // eliding error handling @@ -457,7 +418,7 @@ while num_zeroes != 0 { } this.flush(); // Wait for completion of `flush` -poll-one(pollable); +pollable.block(); // Check for any errors that arose during `flush` let _ = this.check-write(); // eliding error handlingsplice.-
- result<
u64,stream-error>Import interface wasi:filesystem/types@0.2.0-rc-2023-11-10
-WASI filesystem is a filesystem API primarily intended to let users run WASI -programs that access their files on their existing filesystems, without -significant overhead.
-It is intended to be roughly portable between Unix-family platforms and -Windows, though it does not hide many of the major differences.
-Paths are passed as interface-type
-strings, meaning they must consist of -a sequence of Unicode Scalar Values (USVs). Some filesystems may contain -paths which are not accessible by this API.The directory separator in WASI is always the forward-slash (
-/).All paths in WASI are relative paths, and are interpreted relative to a -
-descriptorreferring to a base directory. If apathargument to any WASI -function starts with/, or if any step of resolving apath, including -..and symbolic link steps, reaches a directory outside of the base -directory, or reaches a symlink to an absolute or rooted path in the -underlying filesystem, the function fails witherror-code::not-permitted.For more information about WASI path resolution and sandboxing, see -WASI filesystem path resolution.
+Import interface wasi:cli/stdin@0.2.0-rc-2023-11-10
Types
type input-stream-#### `type output-stream` -[`output-stream`](#output_stream) -
-#### `type error` -[`error`](#error) +---- +
Functions
++
get-stdin: funcReturn values
++
+- own<
+input-stream>Import interface wasi:cli/stdout@0.2.0-rc-2023-11-10
+
+Types
++
type output-stream-#### `type datetime` -[`datetime`](#datetime) +---- +
Functions
++
get-stdout: funcReturn values
++
+- own<
+output-stream>Import interface wasi:cli/stderr@0.2.0-rc-2023-11-10
+
+Types
++
type output-stream-#### `type filesize` -`u64` -
File size or length of a region within a file. -
-
enum descriptor-typeThe type of a filesystem object referenced by a descriptor.
-Note: This was called
-filetypein earlier versions of WASI.Enum Cases
+---- +Functions
++
get-stderr: funcReturn values
-
+- - +
- own<
+output-stream>Import interface wasi:cli/terminal-input@0.2.0-rc-2023-11-10
+
+Types
++
resource terminal-inputThe input side of a terminal.
+Import interface wasi:cli/terminal-output@0.2.0-rc-2023-11-10
+
+Types
++
resource terminal-outputThe output side of a terminal.
+Import interface wasi:cli/terminal-stdin@0.2.0-rc-2023-11-10
+An interface providing an optional
+terminal-inputfor stdin as a +link-time authority.
+Types
++ +
type terminal-input+---- +
Functions
++
get-terminal-stdin: funcIf stdin is connected to a terminal, return a
+terminal-inputhandle +allowing further interaction with it.Return values
++
+- option<own<
+terminal-input>>Import interface wasi:cli/terminal-stdout@0.2.0-rc-2023-11-10
+An interface providing an optional
+terminal-outputfor stdout as a +link-time authority.
+Types
++ +
type terminal-output+---- +
Functions
++
get-terminal-stdout: funcIf stdout is connected to a terminal, return a
+terminal-outputhandle +allowing further interaction with it.Return values
++
+- option<own<
+terminal-output>>Import interface wasi:cli/terminal-stderr@0.2.0-rc-2023-11-10
+An interface providing an optional
+terminal-outputfor stderr as a +link-time authority.
+Types
++ +
type terminal-output+---- +
Functions
++
get-terminal-stderr: funcIf stderr is connected to a terminal, return a
+terminal-outputhandle +allowing further interaction with it.Return values
++
+- option<own<
+terminal-output>>Import interface wasi:clocks/monotonic-clock@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.
+
+Types
++ +
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+
u64A duration of time, in nanoseconds. +
+Functions
++
now: funcRead 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
++
+- +
instant+
resolution: funcQuery the resolution of the clock. Returns the duration of time +corresponding to a clock tick.
+Return values
++
+- +
duration+
subscribe-instant: funcCreate a
+pollablewhich will resolve once the specified instant +occured.Params
+ +Return values
++
+- own<
+pollable>+
subscribe-duration: funcCreate a
+pollablewhich will resolve once the given duration has +elapsed, starting at the time at which this function was called. +occured.Params
+ +Return values
++
+- own<
+pollable>Import interface wasi:clocks/wall-clock@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.
+
+Types
++
record datetimeA time and date in seconds plus nanoseconds.
+Record Fields
++
+- +
seconds:u64- +
nanoseconds:u32
+Functions
++
now: funcRead 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.
+Return values
++
+- +
datetime+
resolution: funcQuery the resolution of the clock.
+The nanoseconds field of the output is always less than 1000000000.
+Return values
++
+- +
datetimeImport interface wasi:filesystem/types@0.2.0-rc-2023-11-10
+WASI filesystem is a filesystem API primarily intended to let users run WASI +programs that access their files on their existing filesystems, without +significant overhead.
+It is intended to be roughly portable between Unix-family platforms and +Windows, though it does not hide many of the major differences.
+Paths are passed as interface-type
+strings, meaning they must consist of +a sequence of Unicode Scalar Values (USVs). Some filesystems may contain +paths which are not accessible by this API.The directory separator in WASI is always the forward-slash (
+/).All paths in WASI are relative paths, and are interpreted relative to a +
+descriptorreferring to a base directory. If apathargument to any WASI +function starts with/, or if any step of resolving apath, including +..and symbolic link steps, reaches a directory outside of the base +directory, or reaches a symlink to an absolute or rooted path in the +underlying filesystem, the function fails witherror-code::not-permitted.For more information about WASI path resolution and sandboxing, see +WASI filesystem path resolution.
+
+Types
++ +
type input-stream+#### `type output-stream` +[`output-stream`](#output_stream) +
+#### `type error` +[`error`](#error) +
+#### `type datetime` +[`datetime`](#datetime) +
+#### `type filesize` +`u64` +
File size or length of a region within a file. +
+
enum descriptor-typeThe type of a filesystem object referenced by a descriptor.
+Note: This was called
+filetypein earlier versions of WASI.Enum Cases
++
- +
@@ -938,8 +1101,11 @@ not reuse it thereafter.The type of the descriptor or file is unknown or is different from any of the other types specified.
+
resource descriptorA descriptor is a reference to a filesystem object, which may be a file, +directory, named pipe, special file, or other object on which filesystem +calls may be made.
-
resource directory-entry-stream
+A stream of directory entries.
Functions
[method]descriptor.read-via-stream: funcReturn a stream for reading from a file, if available.
@@ -1403,6 +1569,9 @@ errors are filesystem-related errors.
Types
+
resource networkAn opaque resource that represents access to (a subset of) the network. +This enables context-based security for networking. +There is no need for this to map 1:1 to a physical network interface.
enum error-codeError codes.
In theory, every API can return any error code. @@ -1584,7 +1753,7 @@ combined with a couple of errors that are always possible:
-
- own<
network>Import interface wasi:sockets/ip-name-lookup@0.2.0-rc-2023-11-10
+Import interface wasi:sockets/udp@0.2.0-rc-2023-11-10
Types
@@ -1596,133 +1765,62 @@ combined with a couple of errors that are always possible: #### `type error-code` [`error-code`](#error_code)
type pollable-#### `type ip-address` -[`ip-address`](#ip_address) +#### `type ip-socket-address` +[`ip-socket-address`](#ip_socket_address)
-#### `resource resolve-address-stream` -
-Functions
--
resolve-addresses: funcResolve 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.
-This function never blocks. It either immediately fails or immediately -returns successfully with a
-resolve-address-streamthat can be used -to (asynchronously) fetch the results.Typical errors
--
-- -
invalid-argument:nameis a syntactically invalid domain name or IP address.References:
+#### `type ip-address-family` +[`ip-address-family`](#ip_address_family) ++#### `record incoming-datagram` +
A received datagram.
+Record Fields
-
-- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html
-- https://man7.org/linux/man-pages/man3/getaddrinfo.3.html
-- https://learn.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo
-- https://man.freebsd.org/cgi/man.cgi?query=getaddrinfo&sektion=3
+- +
++
data: list<u8>The payload. +
Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes.
+- +
+
remote-address:ip-socket-addressThe source address. +
This field is guaranteed to match the remote address the stream was initialized with, if any.
+Equivalent to the
+src_addrout parameter ofrecvfrom.Params
++
record outgoing-datagramA datagram to be sent out.
+Record Fields
-Return values
--
-- result<own<
-resolve-address-stream>,error-code>-
[method]resolve-address-stream.resolve-next-address: funcReturns the next address from the resolver.
-This function should be called multiple times. On each call, it will -return the next address in connection order preference. If all -addresses have been exhausted, this function returns
-none.This function never returns IPv4-mapped IPv6 addresses.
-Typical errors
--
-- -
name-unresolvable: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)- -
temporary-resolver-failure: A temporary failure in name resolution occurred. (EAI_AGAIN)- -
permanent-resolver-failure: A permanent failure in name resolution occurred. (EAI_FAIL)- -
would-block: A result is not available yet. (EWOULDBLOCK, EAGAIN)Params
--
-- -
self: borrow<resolve-address-stream>Return values
--
-- result<option<
-ip-address>,error-code>-
[method]resolve-address-stream.subscribe: funcCreate a
-pollablewhich 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
-futureis natively supported in Preview3.Params
--
-- -
self: borrow<resolve-address-stream>Return values
--
-- own<
-pollable>Import interface wasi:sockets/tcp@0.2.0-rc-2023-11-10
-
-Types
-- -
type input-stream-#### `type output-stream` -[`output-stream`](#output_stream) -
-#### `type pollable` -[`pollable`](#pollable) -
-#### `type duration` -[`duration`](#duration) -
-#### `type network` -[`network`](#network) -
-#### `type error-code` -[`error-code`](#error_code) -
-#### `type ip-socket-address` -[`ip-socket-address`](#ip_socket_address) -
-#### `type ip-address-family` -[`ip-address-family`](#ip_address_family) -
-#### `enum shutdown-type` -
Enum Cases
--
-- - -
Similar to `SHUT_RD` in POSIX. -
- - -
Similar to `SHUT_WR` in POSIX. +
+
data: list<u8>The payload.
- - -
Similar to `SHUT_RDWR` in POSIX. +
+
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
sendin POSIX. Otherwise it is equivalent tosendto.+
resource tcp-socket+
resource udp-socketA UDP socket handle.
++
resource incoming-datagram-stream
resource outgoing-datagram-stream
Functions
-+
[method]tcp-socket.start-bind: func
[method]udp-socket.start-bind: funcBind the socket to a specific network on the provided IP address and port.
If the IP address is zero (
-0.0.0.0in 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.
+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
starterrors
- -
invalid-argument: Thelocal-addresshas the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)- -
invalid-argument:local-addressis not a unicast address. (EINVAL)invalid-argument:local-addressis an IPv4-mapped IPv6 address, but the socket hasipv6-onlyenabled. (EINVAL)invalid-state: The socket is already bound. (EINVAL)Typical
@@ -1742,63 +1840,55 @@ implicitly bind the socket.finisherrorsParams
-
- -
self: borrow<tcp-socket>- -
network: borrow<network>- +
local-address:ip-socket-address- +
self: borrow<udp-socket>- +
network: borrow<network>local-address:ip-socket-addressReturn values
-
-- result<_,
+error-code>- result<_,
error-code>+
[method]tcp-socket.finish-bind: func
[method]udp-socket.finish-bind: funcParams
-
- +
self: borrow<tcp-socket>self: borrow<udp-socket>Return values
-
-- result<_,
-error-code>-
[method]tcp-socket.start-connect: funcConnect 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
+- result<_,
error-code>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:
++
[method]udp-socket.stream: funcSet 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-addressof the socket is updated. Thelocal-addressmay be updated as well, +based on the best network path toremote-address.When a
remote-addressis provided, the returned streams are limited to communicating with that specific peer:-
-- If
-connectfails 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.- +
sendcan only be used to send to this destination.receivewill only return datagrams sent from the providedremote-address.Typical
+starterrorsThis 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
+streamagain.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
-
- -
invalid-argument: Theremote-addresshas the wrong address family. (EAFNOSUPPORT)- -
invalid-argument:remote-addressis not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)invalid-argument:remote-addressis an IPv4-mapped IPv6 address, but the socket hasipv6-onlyenabled. (EINVAL, EADDRNOTAVAIL on Illumos)- -
invalid-argument:remote-addressis 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 inremote-addressis set to INADDR_ANY (0.0.0.0/::). (EADDRNOTAVAIL on Windows)- -
invalid-argument: The port inremote-addressis set to 0. (EADDRNOTAVAIL on Windows)- -
invalid-argument: The socket is already attached to a different network. Thenetworkpassed toconnectmust be identical to the one passed tobind.- -
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
-finisherrors-
- -
timeout: Connection timed out. (ETIMEDOUT)- -
connection-refused: The connection was forcefully rejected. (ECONNREFUSED)- -
connection-reset: The connection was reset. (ECONNRESET)- -
connection-aborted: The connection was aborted. (ECONNABORTED)- +
remote-unreachable: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)- +
invalid-argument: The IP address inremote-addressis set to INADDR_ANY (0.0.0.0/::). (EDESTADDRREQ, EADDRNOTAVAIL)- +
invalid-argument: The port inremote-addressis 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)- -
not-in-progress: Aconnectoperation is not in progress.- +
would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)- +
remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)connection-refused: The connection was refused. (ECONNREFUSED)References
@@ -1809,453 +1899,303 @@ Besides
drop, any method after such a failure may return an error.<Params
-
- -
self: borrow<tcp-socket>- -
network: borrow<network>- +
remote-address:ip-socket-address- +
self: borrow<udp-socket>remote-address: option<ip-socket-address>Return values
-
-- result<_,
+error-code>- result<(own<
incoming-datagram-stream>, own<outgoing-datagram-stream>),error-code>-
[method]tcp-socket.finish-connect: funcParams
++
[method]udp-socket.local-address: funcGet 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
+addressis unspecified.WASI is stricter and requires
+local-addressto returninvalid-statewhen the socket hasn't been bound yet.Typical errors
-
-- +
self: borrow<tcp-socket>invalid-state: The socket is not bound to any local address.Return values
+References
-
-- result<(own<
+input-stream>, own<output-stream>),error-code>- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html
+- https://man7.org/linux/man-pages/man2/getsockname.2.html
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname
+- https://man.freebsd.org/cgi/man.cgi?getsockname
-
[method]tcp-socket.start-listen: funcStart listening for new connections.
-Transitions the socket into the Listener state.
-Unlike POSIX:
+Params
-
-- this function is async. This enables interactive WASI hosts to inject permission prompts.
-- the socket must already be explicitly bound.
+self: borrow<udp-socket>Typical
+starterrorsReturn values
-
-- -
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.- result<
ip-socket-address,error-code>Typical
+finisherrors+
[method]udp-socket.remote-address: funcGet the address the socket is currently streaming to.
+Typical errors
-
- -
address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)- -
not-in-progress: Alistenoperation is not in progress.- +
would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)invalid-state: The socket is not streaming to a specific remote address. (ENOTCONN)References
-
- https://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html
-- https://man7.org/linux/man-pages/man2/listen.2.html
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-listen
-- https://man.freebsd.org/cgi/man.cgi?query=listen&sektion=2
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html
+- https://man7.org/linux/man-pages/man2/getpeername.2.html
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername
+- https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1
Params
-
- +
self: borrow<tcp-socket>self: borrow<udp-socket>Return values
-
-- result<_,
+error-code>- result<
ip-socket-address,error-code>+
[method]tcp-socket.finish-listen: func+
[method]udp-socket.address-family: funcWhether this is a IPv4 or IPv6 socket.
+Equivalent to the SO_DOMAIN socket option.
Params
-
- +
self: borrow<tcp-socket>self: borrow<udp-socket>Return values
-
-- result<_,
+error-code>ip-address-family-
[method]tcp-socket.accept: funcAccept a new client socket.
-The returned socket is bound and in the Connection state. The following properties are inherited from the listener socket:
++
[method]udp-socket.ipv6-only: funcWhether IPv4 compatibility (dual-stack) mode is disabled or not.
+Equivalent to the IPV6_V6ONLY socket option.
+Typical errors
-
-- -
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- +
not-supported: (get/set)thissocket 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.)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
+Params
-
-- -
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)self: borrow<udp-socket>References
+Return values
-
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html
-- https://man7.org/linux/man-pages/man2/accept.2.html
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept
-- https://man.freebsd.org/cgi/man.cgi?query=accept&sektion=2
+- result<
bool,error-code>
[method]udp-socket.set-ipv6-only: funcParams
-
- +
self: borrow<tcp-socket>- +
self: borrow<udp-socket>value:boolReturn values
-
-- result<(own<
+tcp-socket>, own<input-stream>, own<output-stream>),error-code>- result<_,
error-code>-
[method]tcp-socket.local-address: funcGet 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
-addressis unspecified.WASI is stricter and requires
+local-addressto returninvalid-statewhen the socket hasn't been bound yet.+
[method]udp-socket.unicast-hop-limit: funcEquivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+If the provided value is 0, an
invalid-argumenterror is returned.Typical errors
-
-- +
invalid-state: The socket is not bound to any local address.invalid-argument: (set) The TTL value must be 1 or higher.References
+Params
-
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html
-- https://man7.org/linux/man-pages/man2/getsockname.2.html
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname
-- https://man.freebsd.org/cgi/man.cgi?getsockname
+- +
self: borrow<udp-socket>Return values
++
+- result<
u8,error-code>
[method]udp-socket.set-unicast-hop-limit: funcParams
-
- +
self: borrow<tcp-socket>- +
self: borrow<udp-socket>value:u8Return values
-
-- result<
+ip-socket-address,error-code>- result<_,
error-code>-
[method]tcp-socket.remote-address: funcGet the remote address.
++
[method]udp-socket.receive-buffer-size: funcThe kernel buffer space reserved for sends/receives on this socket.
+If the provided value is 0, an
+invalid-argumenterror 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
-
-- -
invalid-state: The socket is not connected to a remote address. (ENOTCONN)References
--
- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html
-- https://man7.org/linux/man-pages/man2/getpeername.2.html
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername
-- https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1
+invalid-argument: (set) The provided value was 0.Params
-
- +
self: borrow<tcp-socket>self: borrow<udp-socket>Return values
-
-- result<
+ip-socket-address,error-code>- result<
u64,error-code>-
[method]tcp-socket.is-listening: funcWhether the socket is listening for new connections.
-Equivalent to the SO_ACCEPTCONN socket option.
+
[method]udp-socket.set-receive-buffer-size: funcParams
-
- +
self: borrow<tcp-socket>- +
self: borrow<udp-socket>value:u64Return values
-
-- +
bool- result<_,
error-code>-
[method]tcp-socket.address-family: funcWhether this is a IPv4 or IPv6 socket.
-Equivalent to the SO_DOMAIN socket option.
+
[method]udp-socket.send-buffer-size: funcParams
-
- +
self: borrow<tcp-socket>self: borrow<udp-socket>Return values
--
[method]tcp-socket.ipv6-only: funcWhether IPv4 compatibility (dual-stack) mode is disabled or not.
-Equivalent to the IPV6_V6ONLY socket option.
-Typical errors
--
+- -
invalid-state: (set) The socket is already bound.- -
not-supported: (get/set)thissocket is an IPv4 socket.- +
not-supported: (set) Host does not support dual-stack sockets. (Implementations are not required to.)- result<
u64,error-code>
[method]udp-socket.set-send-buffer-size: funcParams
-
- +
self: borrow<tcp-socket>- +
self: borrow<udp-socket>value:u64Return values
-
-- result<
+bool,error-code>- result<_,
error-code>+
[method]tcp-socket.set-ipv6-only: func+
[method]udp-socket.subscribe: funcCreate a
+pollablewhich 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
futureis natively supported in Preview3.Params
-
- -
self: borrow<tcp-socket>- +
value:boolself: borrow<udp-socket>Return values
-
+- result<_,
+error-code>- own<
+pollable>+
[method]incoming-datagram-stream.receive: funcReceive messages on the socket.
+This function attempts to receive up to
+max-resultsdatagrams 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-resultsis 0, or:max-resultsis greater than 0, but no results are immediately available. +This function never returnserror(would-block).-
[method]tcp-socket.set-listen-backlog-size: funcHints the desired listen queue size. Implementations are free to ignore this.
-If the provided value is 0, an
invalid-argumenterror is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded.Typical errors
-
-- -
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.- +
remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)connection-refused: The connection was refused. (ECONNREFUSED)Params
+References
-
-- -
self: borrow<tcp-socket>- +
value:u64- https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvfrom.html
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvmsg.html
+- https://man7.org/linux/man-pages/man2/recv.2.html
+- https://man7.org/linux/man-pages/man2/recvmmsg.2.html
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recv
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recvfrom
+- https://learn.microsoft.com/en-us/previous-versions/windows/desktop/legacy/ms741687(v=vs.85)
+- https://man.freebsd.org/cgi/man.cgi?query=recv&sektion=2
Return values
+Params
-
-- result<_,
+error-code>- +
self: borrow<incoming-datagram-stream>max-results:u64-
[method]tcp-socket.keep-alive-enabled: funcEnables or disables keepalive.
-The keepalive behavior can be adjusted using:
+Return values
-
-- -
keep-alive-idle-time- -
keep-alive-interval- +
keep-alive-count-These properties can be configured whilekeep-alive-enabledis false, but only come into effect whenkeep-alive-enabledis true.- result<list<
incoming-datagram>,error-code>Equivalent to the SO_KEEPALIVE socket option.
++
[method]incoming-datagram-stream.subscribe: funcCreate a
+pollablewhich 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
futureis natively supported in Preview3.Params
-
- +
self: borrow<tcp-socket>self: borrow<incoming-datagram-stream>Return values
-
-- result<
+bool,error-code>- own<
pollable>+
[method]tcp-socket.set-keep-alive-enabled: func+
[method]outgoing-datagram-stream.check-send: funcCheck readiness for sending. This function never blocks.
+Returns the number of datagrams permitted for the next call to
+send, +or an error. Callingsendwith more datagrams than this function has +permitted will trap.When this function returns ok(0), the
+subscribepollable will +become ready when this function will report at least ok(1), or an +error.Never returns
would-block.Params
-
- -
self: borrow<tcp-socket>- +
value:boolself: borrow<outgoing-datagram-stream>Return values
-
-- result<_,
+error-code>- result<
u64,error-code>-
[method]tcp-socket.keep-alive-idle-time: funcAmount of time the connection has to be idle before TCP starts sending keepalive packets.
-If the provided value is 0, an
-invalid-argumenterror 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)
++
[method]outgoing-datagram-stream.send: funcSend messages on the socket.
+This function attempts to send all provided
+datagramson the socket without blocking and +returns how many messages were actually sent (or queued for sending). This function never +returnserror(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
+datagramslist 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
sendmust be permitted by a precedingcheck-send. Implementations must trap if +eithercheck-sendwas not called ordatagramscontains more items thancheck-sendpermitted.Typical errors
-
-- -
invalid-argument: (set) The provided value was 0.Params
--
-- +
self: borrow<tcp-socket>- +
invalid-argument: Theremote-addresshas the wrong address family. (EAFNOSUPPORT)- +
invalid-argument:remote-addressis 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 inremote-addressis set to INADDR_ANY (0.0.0.0/::). (EDESTADDRREQ, EADDRNOTAVAIL)- +
invalid-argument: The port inremote-addressis set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)- +
invalid-argument: The socket is in "connected" mode andremote-addressissomevalue that does not match the address passed tostream. (EISCONN)- +
invalid-argument: The socket is not "connected" and no value forremote-addresswas 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)Return values
+References
-
-- result<
+duration,error-code>- https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendto.html
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendmsg.html
+- https://man7.org/linux/man-pages/man2/send.2.html
+- https://man7.org/linux/man-pages/man2/sendmmsg.2.html
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-send
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-sendto
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasendmsg
+- https://man.freebsd.org/cgi/man.cgi?query=send&sektion=2
[method]tcp-socket.set-keep-alive-idle-time: funcParams
-
- -
self: borrow<tcp-socket>- +
value:duration- +
self: borrow<outgoing-datagram-stream>datagrams: list<outgoing-datagram>Return values
-
-- result<_,
-error-code>-
[method]tcp-socket.keep-alive-interval: funcThe time between keepalive packets.
-If the provided value is 0, an
-invalid-argumenterror 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
--
+- +
invalid-argument: (set) The provided value was 0.- result<
u64,error-code>+
[method]outgoing-datagram-stream.subscribe: funcCreate a
+pollablewhich 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
futureis natively supported in Preview3.Params
-
- +
self: borrow<tcp-socket>self: borrow<outgoing-datagram-stream>Return values
-
-- result<
+duration,error-code>- own<
pollable>-
[method]tcp-socket.set-keep-alive-interval: funcParams
--
-- -
self: borrow<tcp-socket>- -
value:durationReturn values
--
-- result<_,
-error-code>-
[method]tcp-socket.keep-alive-count: funcThe maximum amount of keepalive packets TCP should send before aborting the connection.
-If the provided value is 0, an
-invalid-argumenterror 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
--
-- -
self: borrow<tcp-socket>Return values
--
-- result<
-u32,error-code>-
[method]tcp-socket.set-keep-alive-count: funcParams
--
-- -
self: borrow<tcp-socket>- -
value:u32Return values
--
-- result<_,
-error-code>-
[method]tcp-socket.hop-limit: funcEquivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
-If the provided value is 0, an
-invalid-argumenterror is returned.Typical errors
--
-- -
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
--
-- -
self: borrow<tcp-socket>Return values
--
-- result<
-u8,error-code>-
[method]tcp-socket.set-hop-limit: funcParams
--
-- -
self: borrow<tcp-socket>- -
value:u8Return values
--
-- result<_,
-error-code>-
[method]tcp-socket.receive-buffer-size: funcThe kernel buffer space reserved for sends/receives on this socket.
-If the provided value is 0, an
-invalid-argumenterror 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
--
-- -
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
--
-- -
self: borrow<tcp-socket>Return values
--
-- result<
-u64,error-code>-
[method]tcp-socket.set-receive-buffer-size: funcParams
--
-- -
self: borrow<tcp-socket>- -
value:u64Return values
--
-- result<_,
-error-code>-
[method]tcp-socket.send-buffer-size: funcParams
--
-- -
self: borrow<tcp-socket>Return values
--
-- result<
-u64,error-code>-
[method]tcp-socket.set-send-buffer-size: funcParams
--
-- -
self: borrow<tcp-socket>- -
value:u64Return values
--
-- result<_,
-error-code>-
[method]tcp-socket.subscribe: funcCreate a
-pollablewhich 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
-futureis natively supported in Preview3.Params
--
-- -
self: borrow<tcp-socket>Return values
--
-- own<
-pollable>-
[method]tcp-socket.shutdown: funcInitiate a graceful shutdown.
--
-- receive: the socket is not expecting to receive any more data from the peer. All subsequent read -operations on the
-input-streamassociated with this socket will return an End Of Stream indication. -Any data still in the receive queue at time of callingshutdownwill be discarded.- send: the socket is not expecting to send any more data to the peer. All subsequent write -operations on the
-output-streamassociated 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
--
-- -
invalid-state: The socket is not in the Connection state. (ENOTCONN)References
--
-- https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html
-- https://man7.org/linux/man-pages/man2/shutdown.2.html
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-shutdown
-- https://man.freebsd.org/cgi/man.cgi?query=shutdown&sektion=2
-Params
--
-- -
self: borrow<tcp-socket>- -
shutdown-type:shutdown-typeReturn values
--
-- result<_,
-error-code>Import interface wasi:sockets/tcp-create-socket@0.2.0-rc-2023-11-10
+Import interface wasi:sockets/udp-create-socket@0.2.0-rc-2023-11-10
Types
@@ -2267,24 +2207,24 @@ operations on the
type networkoutput-streamassoci #### `type ip-address-family` [`ip-address-family`](#ip_address_family)-#### `type tcp-socket` -[`tcp-socket`](#tcp_socket) +#### `type udp-socket` +[`udp-socket`](#udp_socket)
----
Functions
--
create-tcp-socket: funcCreate a new TCP socket.
-Similar to
+socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP)in POSIX.+
create-udp-socket: funcCreate 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
+at time of creation, the socket is not bound to anynetworkyet. Up to the momentbind/listen/connect-is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world.networkyet. Up to the momentbindis 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 specifiedaddress-familyis not supported. (EAFNOSUPPORT)new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)References
+References:
- https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html
- https://man7.org/linux/man-pages/man2/socket.2.html
@@ -2293,17 +2233,26 @@ is called, the socket is effectively an in-memory configuration object, unable tParams
Return values
-
-- result<own<
+tcp-socket>,error-code>- result<own<
udp-socket>,error-code>Import interface wasi:sockets/udp@0.2.0-rc-2023-11-10
+Import interface wasi:sockets/tcp@0.2.0-rc-2023-11-10
Types
-- +
type pollable+ +
type input-stream+#### `type output-stream` +[`output-stream`](#output_stream) +
+#### `type pollable` +[`pollable`](#pollable) +
+#### `type duration` +[`duration`](#duration)
#### `type network` [`network`](#network) @@ -2317,55 +2266,38 @@ is called, the socket is effectively an in-memory configuration object, unable t #### `type ip-address-family` [`ip-address-family`](#ip_address_family)
-#### `record incoming-datagram` -
A received datagram.
-Record Fields
+#### `enum shutdown-type` +Enum Cases
-
- -
--
data: list<u8>The payload. -
Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes.
-- -
--
remote-address:ip-socket-addressThe source address. -
This field is guaranteed to match the remote address the stream was initialized with, if any.
-Equivalent to the
+ +src_addrout parameter ofrecvfrom.Similar to `SHUT_RD` in POSIX.
-
record outgoing-datagramA datagram to be sent out.
-Record Fields
--
- -
-
data: list<u8>The payload. +
+Similar to `SHUT_WR` in POSIX.
- -
-
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
+ +sendin POSIX. Otherwise it is equivalent tosendto.Similar to `SHUT_RDWR` in POSIX.
-
resource udp-socket-
resource incoming-datagram-stream-
resource outgoing-datagram-stream
++
resource tcp-socketA TCP socket handle.
Functions
-+
[method]udp-socket.start-bind: func
[method]tcp-socket.start-bind: funcBind the socket to a specific network on the provided IP address and port.
If the IP address is zero (
+If the TCP/UDP port is zero, the socket will be bound to a random free port. +0.0.0.0in IPv4,::in IPv6), it is left to the implementation to decide which network interface(s) to bind to. -If the 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
starterrors
- +
invalid-argument: Thelocal-addresshas the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)- +
invalid-argument:local-addressis not a unicast address. (EINVAL)invalid-argument:local-addressis an IPv4-mapped IPv6 address, but the socket hasipv6-onlyenabled. (EINVAL)invalid-state: The socket is already bound. (EINVAL)Typical
@@ -2385,55 +2317,63 @@ If the port is zero, the socket will be bound to a random free port.finisherrorsParams
-
- -
self: borrow<udp-socket>- -
network: borrow<network>- +
local-address:ip-socket-address- +
self: borrow<tcp-socket>- +
network: borrow<network>local-address:ip-socket-addressReturn values
-
-- result<_,
+error-code>- result<_,
error-code>+
[method]udp-socket.finish-bind: func
[method]tcp-socket.finish-bind: funcParams
-
- +
self: borrow<udp-socket>self: borrow<tcp-socket>Return values
-
-- result<_,
+error-code>- result<_,
error-code>-
[method]udp-socket.stream: funcSet 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-addressof the socket is updated. Thelocal-addressmay be updated as well, -based on the best network path toremote-address.When a
+remote-addressis provided, the returned streams are limited to communicating with that specific peer:+
[method]tcp-socket.start-connect: funcConnect to a remote endpoint.
+On success:
-
-- -
sendcan only be used to send to this destination.- +
receivewill only return datagrams sent from the providedremote-address.- the socket is transitioned into the Connection state
+- a pair of streams is returned that can be used to read & write to the connection
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
-streamagain.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
+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
+connectfails 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
starterrors+
- +
invalid-argument: Theremote-addresshas the wrong address family. (EAFNOSUPPORT)- +
invalid-argument:remote-addressis not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)invalid-argument:remote-addressis an IPv4-mapped IPv6 address, but the socket hasipv6-onlyenabled. (EINVAL, EADDRNOTAVAIL on Illumos)- -
invalid-argument:remote-addressis 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 inremote-addressis set to INADDR_ANY (0.0.0.0/::). (EDESTADDRREQ, EADDRNOTAVAIL)- -
invalid-argument: The port inremote-addressis set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)- +
invalid-state: The socket is not bound.- +
invalid-argument: The IP address inremote-addressis set to INADDR_ANY (0.0.0.0/::). (EADDRNOTAVAIL on Windows)- +
invalid-argument: The port inremote-addressis set to 0. (EADDRNOTAVAIL on Windows)- +
invalid-argument: The socket is already attached to a different network. Thenetworkpassed toconnectmust be identical to the one passed tobind.- +
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
+finisherrors+
- +
timeout: Connection timed out. (ETIMEDOUT)- +
connection-refused: The connection was forcefully rejected. (ECONNREFUSED)- +
connection-reset: The connection was reset. (ECONNRESET)- +
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)- -
remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)- +
connection-refused: The connection was refused. (ECONNREFUSED)- +
not-in-progress: Aconnectoperation is not in progress.would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)References
@@ -2444,15 +2384,107 @@ if (remote_address is Some) {
Params
-
- -
self: borrow<udp-socket>- +
remote-address: option<ip-socket-address>- +
self: borrow<tcp-socket>- +
network: borrow<network>remote-address:ip-socket-addressReturn values
-
-- result<(own<
+incoming-datagram-stream>, own<outgoing-datagram-stream>),error-code>- result<_,
error-code>-
[method]udp-socket.local-address: funcGet the current bound address.
++
[method]tcp-socket.finish-connect: funcParams
++
+- +
self: borrow<tcp-socket>Return values
++
+- result<(own<
+input-stream>, own<output-stream>),error-code>+
[method]tcp-socket.start-listen: funcStart 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
+starterrors+
+- +
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
+finisherrors+
+- +
address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)- +
not-in-progress: Alistenoperation is not in progress.- +
would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)References
++
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html
+- https://man7.org/linux/man-pages/man2/listen.2.html
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-listen
+- https://man.freebsd.org/cgi/man.cgi?query=listen&sektion=2
+Params
++
+- +
self: borrow<tcp-socket>Return values
++
+- result<_,
+error-code>+
[method]tcp-socket.finish-listen: funcParams
++
+- +
self: borrow<tcp-socket>Return values
++
+- result<_,
+error-code>+
[method]tcp-socket.accept: funcAccept a new client socket.
+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-sizeOn 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
++
+- +
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
++
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html
+- https://man7.org/linux/man-pages/man2/accept.2.html
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept
+- https://man.freebsd.org/cgi/man.cgi?query=accept&sektion=2
+Params
++
+- +
self: borrow<tcp-socket>Return values
++
+- result<(own<
+tcp-socket>, own<input-stream>, own<output-stream>),error-code>+
[method]tcp-socket.local-address: funcGet the bound local address.
POSIX mentions:
If the socket has not been bound to a local name, the value @@ -2465,282 +2497,340 @@ stored in the object pointed to by
addressis unspecified.References
-
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html
-- https://man7.org/linux/man-pages/man2/getsockname.2.html
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname
-- https://man.freebsd.org/cgi/man.cgi?getsockname
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html
+- https://man7.org/linux/man-pages/man2/getsockname.2.html
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname
+- https://man.freebsd.org/cgi/man.cgi?getsockname
+Params
++
+- +
self: borrow<tcp-socket>Return values
++
+- result<
+ip-socket-address,error-code>+
[method]tcp-socket.remote-address: funcGet the remote address.
+Typical errors
++
+- +
invalid-state: The socket is not connected to a remote address. (ENOTCONN)References
++
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html
+- https://man7.org/linux/man-pages/man2/getpeername.2.html
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername
+- https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1
+Params
++
+- +
self: borrow<tcp-socket>Return values
++
+- result<
+ip-socket-address,error-code>+
[method]tcp-socket.is-listening: funcWhether the socket is listening for new connections.
+Equivalent to the SO_ACCEPTCONN socket option.
+Params
++
+- +
self: borrow<tcp-socket>Return values
+ ++
[method]tcp-socket.address-family: funcWhether this is a IPv4 or IPv6 socket.
+Equivalent to the SO_DOMAIN socket option.
+Params
++
+- +
self: borrow<tcp-socket>Return values
+ ++
[method]tcp-socket.ipv6-only: funcWhether IPv4 compatibility (dual-stack) mode is disabled or not.
+Equivalent to the IPV6_V6ONLY socket option.
+Typical errors
++
+- +
invalid-state: (set) The socket is already bound.- +
not-supported: (get/set)thissocket is an IPv4 socket.- +
not-supported: (set) Host does not support dual-stack sockets. (Implementations are not required to.)Params
++
+- +
self: borrow<tcp-socket>Return values
++
+- result<
+bool,error-code>+
[method]tcp-socket.set-ipv6-only: funcParams
++
+- +
self: borrow<tcp-socket>- +
value:boolReturn values
++
+- result<_,
+error-code>+
[method]tcp-socket.set-listen-backlog-size: funcHints the desired listen queue size. Implementations are free to ignore this.
+If the provided value is 0, an
+invalid-argumenterror is returned. +Any other value will never cause an error, but it might be silently clamped and/or rounded.Typical errors
++
- +
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
-
- +
self: borrow<udp-socket>- +
self: borrow<tcp-socket>value:u64Return values
-
-- result<
-ip-socket-address,error-code>-
[method]udp-socket.remote-address: funcGet the address the socket is currently streaming to.
-Typical errors
--
-- +
invalid-state: The socket is not streaming to a specific remote address. (ENOTCONN)- result<_,
error-code>References
++
[method]tcp-socket.keep-alive-enabled: funcEnables or disables keepalive.
+The keepalive behavior can be adjusted using:
-
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html
-- https://man7.org/linux/man-pages/man2/getpeername.2.html
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername
-- https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1
+- +
keep-alive-idle-time- +
keep-alive-intervalkeep-alive-count+These properties can be configured whilekeep-alive-enabledis false, but only come into effect whenkeep-alive-enabledis true.Equivalent to the SO_KEEPALIVE socket option.
Params
-
- +
self: borrow<udp-socket>self: borrow<tcp-socket>Return values
-
-- result<
+ip-socket-address,error-code>- result<
bool,error-code>-
[method]udp-socket.address-family: funcWhether this is a IPv4 or IPv6 socket.
-Equivalent to the SO_DOMAIN socket option.
+
[method]tcp-socket.set-keep-alive-enabled: funcParams
-
- +
self: borrow<udp-socket>- +
self: borrow<tcp-socket>value:boolReturn values
-
-- +
ip-address-family- result<_,
error-code>-
[method]udp-socket.ipv6-only: funcWhether IPv4 compatibility (dual-stack) mode is disabled or not.
-Equivalent to the IPV6_V6ONLY socket option.
++
[method]tcp-socket.keep-alive-idle-time: funcAmount of time the connection has to be idle before TCP starts sending keepalive packets.
+If the provided value is 0, an
+invalid-argumenterror 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
-
- -
not-supported: (get/set)thissocket 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.)invalid-argument: (set) The provided value was 0.Params
-
- +
self: borrow<udp-socket>self: borrow<tcp-socket>Return values
-
-- result<
+bool,error-code>- result<
duration,error-code>+
[method]udp-socket.set-ipv6-only: func
[method]tcp-socket.set-keep-alive-idle-time: funcParams
-
- -
self: borrow<udp-socket>- +
value:bool- +
self: borrow<tcp-socket>value:durationReturn values
-
-- result<_,
+error-code>- result<_,
error-code>-
[method]udp-socket.unicast-hop-limit: funcEquivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
-If the provided value is 0, an
+invalid-argumenterror is returned.+
[method]tcp-socket.keep-alive-interval: funcThe time between keepalive packets.
+If the provided value is 0, an
+invalid-argumenterror 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
-
- +
invalid-argument: (set) The TTL value must be 1 or higher.invalid-argument: (set) The provided value was 0.Params
-
- +
self: borrow<udp-socket>self: borrow<tcp-socket>Return values
-
-- result<
+u8,error-code>- result<
duration,error-code>+
[method]udp-socket.set-unicast-hop-limit: func
[method]tcp-socket.set-keep-alive-interval: funcParams
-
- -
self: borrow<udp-socket>- +
value:u8- +
self: borrow<tcp-socket>value:durationReturn values
-
-- result<_,
+error-code>- result<_,
error-code>-
[method]udp-socket.receive-buffer-size: funcThe kernel buffer space reserved for sends/receives on this socket.
++
[method]tcp-socket.keep-alive-count: funcThe maximum amount of keepalive packets TCP should send before aborting the connection.
If the provided value is 0, an
-invalid-argumenterror 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.
+Equivalent to the TCP_KEEPCNT socket option.
Typical errors
invalid-argument: (set) The provided value was 0.Params
-
- +
self: borrow<udp-socket>self: borrow<tcp-socket>Return values
-
-- result<
+u64,error-code>- result<
u32,error-code>+
[method]udp-socket.set-receive-buffer-size: func
[method]tcp-socket.set-keep-alive-count: funcParams
-
- -
self: borrow<udp-socket>- +
value:u64- +
self: borrow<tcp-socket>value:u32Return values
-
-- result<_,
-error-code>-
[method]udp-socket.send-buffer-size: funcParams
--
-- +
self: borrow<udp-socket>- result<_,
error-code>Return values
++
[method]tcp-socket.hop-limit: funcEquivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+If the provided value is 0, an
+invalid-argumenterror is returned.Typical errors
-
-- result<
+u64,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.
[method]udp-socket.set-send-buffer-size: funcParams
-
- -
self: borrow<udp-socket>- +
value:u64self: borrow<tcp-socket>Return values
-
-- result<_,
+error-code>- result<
u8,error-code>-
[method]udp-socket.subscribe: funcCreate a
-pollablewhich 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
+futureis natively supported in Preview3.
[method]tcp-socket.set-hop-limit: funcParams
-
- +
self: borrow<udp-socket>- +
self: borrow<tcp-socket>value:u8Return values
-
-- own<
+pollable>- result<_,
error-code>-
[method]incoming-datagram-stream.receive: funcReceive messages on the socket.
-This function attempts to receive up to
-max-resultsdatagrams 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:
++
[method]tcp-socket.receive-buffer-size: funcThe kernel buffer space reserved for sends/receives on this socket.
+If the provided value is 0, an
+invalid-argumenterror 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
-
-- -
max-resultsis 0, or:- +
max-resultsis greater than 0, but no results are immediately available. -This function never returnserror(would-block).- +
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.Typical errors
+Params
-
-- -
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<tcp-socket>References
+Return values
-
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvfrom.html
-- https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvmsg.html
-- https://man7.org/linux/man-pages/man2/recv.2.html
-- https://man7.org/linux/man-pages/man2/recvmmsg.2.html
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recv
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recvfrom
-- https://learn.microsoft.com/en-us/previous-versions/windows/desktop/legacy/ms741687(v=vs.85)
-- https://man.freebsd.org/cgi/man.cgi?query=recv&sektion=2
+- result<
u64,error-code>
[method]tcp-socket.set-receive-buffer-size: funcParams
-
- -
self: borrow<incoming-datagram-stream>- +
max-results:u64- +
self: borrow<tcp-socket>value:u64Return values
-
-- result<list<
+incoming-datagram>,error-code>- result<_,
error-code>-
[method]incoming-datagram-stream.subscribe: funcCreate a
-pollablewhich 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
+futureis natively supported in Preview3.
[method]tcp-socket.send-buffer-size: funcParams
-
- +
self: borrow<incoming-datagram-stream>self: borrow<tcp-socket>Return values
-
-- own<
+pollable>- result<
u64,error-code>-
[method]outgoing-datagram-stream.check-send: funcCheck readiness for sending. This function never blocks.
-Returns the number of datagrams permitted for the next call to
-send, -or an error. Callingsendwith more datagrams than this function has -permitted will trap.When this function returns ok(0), the
-subscribepollable will -become ready when this function will report at least ok(1), or an -error.Never returns
+would-block.
[method]tcp-socket.set-send-buffer-size: funcParams
-
- +
self: borrow<outgoing-datagram-stream>- +
self: borrow<tcp-socket>value:u64Return values
-
-- result<
+u64,error-code>- result<_,
error-code>-
[method]outgoing-datagram-stream.send: funcSend messages on the socket.
-This function attempts to send all provided
-datagramson the socket without blocking and -returns how many messages were actually sent (or queued for sending). This function never -returnserror(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
-datagramslist 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
-sendmust be permitted by a precedingcheck-send. Implementations must trap if -eithercheck-sendwas not called ordatagramscontains more items thancheck-sendpermitted.Typical errors
++
[method]tcp-socket.subscribe: funcCreate a
+pollablewhich 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
+futureis natively supported in Preview3.Params
-
-- -
invalid-argument: Theremote-addresshas the wrong address family. (EAFNOSUPPORT)- -
invalid-argument:remote-addressis 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 inremote-addressis set to INADDR_ANY (0.0.0.0/::). (EDESTADDRREQ, EADDRNOTAVAIL)- -
invalid-argument: The port inremote-addressis set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)- -
invalid-argument: The socket is in "connected" mode andremote-addressissomevalue that does not match the address passed tostream. (EISCONN)- -
invalid-argument: The socket is not "connected" and no value forremote-addresswas 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<tcp-socket>References
+Return values
-
-- https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendto.html
-- https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendmsg.html
-- https://man7.org/linux/man-pages/man2/send.2.html
-- https://man7.org/linux/man-pages/man2/sendmmsg.2.html
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-send
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-sendto
-- https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasendmsg
-- https://man.freebsd.org/cgi/man.cgi?query=send&sektion=2
+- own<
pollable>Params
++
[method]tcp-socket.shutdown: funcInitiate a graceful shutdown.
++
+- receive: the socket is not expecting to receive any more data from the peer. All subsequent read +operations on the
+input-streamassociated with this socket will return an End Of Stream indication. +Any data still in the receive queue at time of callingshutdownwill be discarded.- send: the socket is not expecting to send any more data to the peer. All subsequent write +operations on the
+output-streamassociated 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
-
-- -
self: borrow<outgoing-datagram-stream>- +
datagrams: list<outgoing-datagram>invalid-state: The socket is not in the Connection state. (ENOTCONN)Return values
+References
-
-- result<
+u64,error-code>- https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html
+- https://man7.org/linux/man-pages/man2/shutdown.2.html
+- https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-shutdown
+- https://man.freebsd.org/cgi/man.cgi?query=shutdown&sektion=2
-
[method]outgoing-datagram-stream.subscribe: funcCreate a
-pollablewhich 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
futureis natively supported in Preview3.Params
-
- +
self: borrow<outgoing-datagram-stream>- +
self: borrow<tcp-socket>shutdown-type:shutdown-typeReturn values
-
-- own<
+pollable>- result<_,
error-code>Import interface wasi:sockets/udp-create-socket@0.2.0-rc-2023-11-10
+Import interface wasi:sockets/tcp-create-socket@0.2.0-rc-2023-11-10
Types
@@ -2752,24 +2842,24 @@ It's planned to be removed when
type networkfutureis natively supported in Pre #### `type ip-address-family` [`ip-address-family`](#ip_address_family)-#### `type udp-socket` -[`udp-socket`](#udp_socket) +#### `type tcp-socket` +[`tcp-socket`](#tcp_socket)
----
Functions
--
create-udp-socket: funcCreate a new UDP socket.
-Similar to
+socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP)in POSIX.+
create-tcp-socket: funcCreate 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
+at time of creation, the socket is not bound to anynetworkyet. Up to the momentbindis called, -the socket is effectively an in-memory configuration object, unable to communicate with the outside world.networkyet. Up to the momentbind/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 specifiedaddress-familyis not supported. (EAFNOSUPPORT)new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)References:
+References
- https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html
- https://man7.org/linux/man-pages/man2/socket.2.html
@@ -2778,11 +2868,91 @@ the socket is effectively an in-memory configuration object, unable to communicaParams
Return values
-
+- result<own<
+udp-socket>,error-code>- result<own<
+tcp-socket>,error-code>Import interface wasi:sockets/ip-name-lookup@0.2.0-rc-2023-11-10
+
+Types
++ +
type pollable+#### `type network` +[`network`](#network) +
+#### `type error-code` +[`error-code`](#error_code) +
+#### `type ip-address` +[`ip-address`](#ip_address) +
+#### `resource resolve-address-stream` +
+Functions
++
resolve-addresses: funcResolve 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.
+This function never blocks. It either immediately fails or immediately +returns successfully with a
+resolve-address-streamthat can be used +to (asynchronously) fetch the results.Typical errors
++
+- +
invalid-argument:nameis a syntactically invalid domain name or IP address.References:
++
+- https://pubs.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html
+- https://man7.org/linux/man-pages/man3/getaddrinfo.3.html
+- https://learn.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo
+- https://man.freebsd.org/cgi/man.cgi?query=getaddrinfo&sektion=3
+Params
+ +Return values
++
+- result<own<
+resolve-address-stream>,error-code>+
[method]resolve-address-stream.resolve-next-address: funcReturns the next address from the resolver.
+This function should be called multiple times. On each call, it will +return the next address in connection order preference. If all +addresses have been exhausted, this function returns
+none.This function never returns IPv4-mapped IPv6 addresses.
+Typical errors
++
+- +
name-unresolvable: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)- +
temporary-resolver-failure: A temporary failure in name resolution occurred. (EAI_AGAIN)- +
permanent-resolver-failure: A permanent failure in name resolution occurred. (EAI_FAIL)- +
would-block: A result is not available yet. (EWOULDBLOCK, EAGAIN)Params
++
+- +
self: borrow<resolve-address-stream>Return values
++
+- result<option<
+ip-address>,error-code>+
[method]resolve-address-stream.subscribe: funcCreate a
+pollablewhich 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
+futureis natively supported in Preview3.Params
++
+- +
self: borrow<resolve-address-stream>Return values
++
- own<
pollable>Import interface wasi:random/random@0.2.0-rc-2023-11-10
WASI Random is a random data API.
@@ -2870,137 +3040,3 @@ protection. -Import interface wasi:cli/environment@0.2.0-rc-2023-11-10
-
-Functions
--
get-environment: funcGet the POSIX-style environment variables.
-Each environment variable is provided as a pair of string variable names -and string value.
-Morally, these are a value import, but until value imports are available -in the component model, this import function should return the same -values each time it is called.
-Return values
- --
get-arguments: funcGet the POSIX-style arguments to the program.
-Return values
- --
initial-cwd: funcReturn a path that programs should use as their initial current working -directory, interpreting
-.as shorthand for this.Return values
- -Import interface wasi:cli/exit@0.2.0-rc-2023-11-10
-
-Functions
--
exit: funcExit the current instance and any linked instances.
-Params
--
-- -
status: resultImport interface wasi:cli/stdin@0.2.0-rc-2023-11-10
-
-Types
-- -
type input-stream----- -
Functions
--
get-stdin: funcReturn values
--
-- own<
-input-stream>Import interface wasi:cli/stdout@0.2.0-rc-2023-11-10
-
-Types
-- -
type output-stream----- -
Functions
--
get-stdout: funcReturn values
--
-- own<
-output-stream>Import interface wasi:cli/stderr@0.2.0-rc-2023-11-10
-
-Types
-- -
type output-stream----- -
Functions
--
get-stderr: funcReturn values
--
-- own<
-output-stream>Import interface wasi:cli/terminal-input@0.2.0-rc-2023-11-10
-
-Types
--
resource terminal-inputImport interface wasi:cli/terminal-output@0.2.0-rc-2023-11-10
-
-Types
--
resource terminal-outputImport interface wasi:cli/terminal-stdin@0.2.0-rc-2023-11-10
-An interface providing an optional
-terminal-inputfor stdin as a -link-time authority.
-Types
-- -
type terminal-input----- -
Functions
--
get-terminal-stdin: funcIf stdin is connected to a terminal, return a
-terminal-inputhandle -allowing further interaction with it.Return values
--
-- option<own<
-terminal-input>>Import interface wasi:cli/terminal-stdout@0.2.0-rc-2023-11-10
-An interface providing an optional
-terminal-outputfor stdout as a -link-time authority.
-Types
-- -
type terminal-output----- -
Functions
--
get-terminal-stdout: funcIf stdout is connected to a terminal, return a
-terminal-outputhandle -allowing further interaction with it.Return values
--
-- option<own<
-terminal-output>>Import interface wasi:cli/terminal-stderr@0.2.0-rc-2023-11-10
-An interface providing an optional
-terminal-outputfor stderr as a -link-time authority.
-Types
-- -
type terminal-output----- -
Functions
--
get-terminal-stderr: funcIf stderr is connected to a terminal, return a
-terminal-outputhandle -allowing further interaction with it.Return values
--
diff --git a/wit/command.wit b/wit/command.wit index 74811d3..a46274b 100644 --- a/wit/command.wit +++ b/wit/command.wit @@ -1,7 +1,7 @@ package wasi:cli@0.2.0-rc-2023-11-10; world command { - include reactor; + include imports; export run; } diff --git a/wit/deps.lock b/wit/deps.lock index cbaafcb..d8a7653 100644 --- a/wit/deps.lock +++ b/wit/deps.lock @@ -10,8 +10,8 @@ sha512 = "2c242489801a75466986fe014d730fb3aa7b5c6e56a230c8735e6672711b58bcbe92ba [io] url = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz" -sha256 = "f2e6127b235c37c06be675a904d6acf08db953ea688d78c42892c6ad3bd194e4" -sha512 = "32feefbc115c34bf6968cb6e9dc15e755698ee90648e5a5d84448917c36a318bd61b401195eb64330e2475e1d098bfb8dee1440d594a68e0797748762bd84ae5" +sha256 = "b622db2755978a49d18d35d84d75f66b2b1ed23d7bf413e5c9e152e190cc7d4b" +sha512 = "d19c9004e75bf3ebe3e34cff498c3d7fee04cd57a7fba7ed12a0c5ad842ba5715c009de77a152c57da0500f6ca0986b6791b6f022829bdd5a024f7bc114c2ff6" [random] url = "https://github.com/WebAssembly/wasi-random/archive/main.tar.gz" diff --git a/wit/deps/io/poll.wit b/wit/deps/io/poll.wit index bddde3c..81b1cab 100644 --- a/wit/deps/io/poll.wit +++ b/wit/deps/io/poll.wit @@ -3,7 +3,7 @@ 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. interface poll { - /// `pollable` epresents a single I/O event which may be ready, or not. + /// `pollable` represents a single I/O event which may be ready, or not. resource pollable { /// Return the readiness of a pollable. This function never blocks. diff --git a/wit/deps/io/streams.wit b/wit/deps/io/streams.wit index e7e1b68..f6f7fe0 100644 --- a/wit/deps/io/streams.wit +++ b/wit/deps/io/streams.wit @@ -131,7 +131,7 @@ interface streams { /// let pollable = this.subscribe(); /// while !contents.is_empty() { /// // Wait for the stream to become writable - /// poll-one(pollable); + /// pollable.block(); /// let Ok(n) = this.check-write(); // eliding error handling /// let len = min(n, contents.len()); /// let (chunk, rest) = contents.split_at(len); @@ -140,7 +140,7 @@ interface streams { /// } /// this.flush(); /// // Wait for completion of `flush` - /// poll-one(pollable); + /// pollable.block(); /// // Check for any errors that arose during `flush` /// let _ = this.check-write(); // eliding error handling /// ``` @@ -178,7 +178,7 @@ interface streams { /// Write zeroes to a stream. /// - /// this should be used precisely like `write` with the exact same + /// This should be used precisely like `write` with the exact same /// preconditions (must use check-write first), but instead of /// passing a list of bytes, you simply pass the number of zero-bytes /// that should be written. @@ -199,7 +199,7 @@ interface streams { /// let pollable = this.subscribe(); /// while num_zeroes != 0 { /// // Wait for the stream to become writable - /// poll-one(pollable); + /// pollable.block(); /// let Ok(n) = this.check-write(); // eliding error handling /// let len = min(n, num_zeroes); /// this.write-zeroes(len); // eliding error handling @@ -207,7 +207,7 @@ interface streams { /// } /// this.flush(); /// // Wait for completion of `flush` - /// poll-one(pollable); + /// pollable.block(); /// // Check for any errors that arose during `flush` /// let _ = this.check-write(); // eliding error handling /// ``` diff --git a/wit/imports.wit b/wit/imports.wit new file mode 100644 index 0000000..63dabfc --- /dev/null +++ b/wit/imports.wit @@ -0,0 +1,20 @@ +package wasi:cli@0.2.0-rc-2023-11-10; + +world imports { + include wasi:clocks/imports@0.2.0-rc-2023-11-10; + include wasi:filesystem/imports@0.2.0-rc-2023-11-10; + include wasi:sockets/imports@0.2.0-rc-2023-11-10; + include wasi:random/imports@0.2.0-rc-2023-11-10; + include wasi:io/imports@0.2.0-rc-2023-11-10; + + import environment; + import exit; + import stdin; + import stdout; + import stderr; + import terminal-input; + import terminal-output; + import terminal-stdin; + import terminal-stdout; + import terminal-stderr; +} diff --git a/wit/reactor.wit b/wit/reactor.wit deleted file mode 100644 index eafa2fd..0000000 --- a/wit/reactor.wit +++ /dev/null @@ -1,31 +0,0 @@ -package wasi:cli@0.2.0-rc-2023-11-10; - -world reactor { - import wasi:clocks/wall-clock@0.2.0-rc-2023-11-10; - import wasi:clocks/monotonic-clock@0.2.0-rc-2023-11-10; - import wasi:filesystem/types@0.2.0-rc-2023-11-10; - import wasi:filesystem/preopens@0.2.0-rc-2023-11-10; - import wasi:sockets/instance-network@0.2.0-rc-2023-11-10; - import wasi:sockets/ip-name-lookup@0.2.0-rc-2023-11-10; - import wasi:sockets/network@0.2.0-rc-2023-11-10; - import wasi:sockets/tcp-create-socket@0.2.0-rc-2023-11-10; - import wasi:sockets/tcp@0.2.0-rc-2023-11-10; - import wasi:sockets/udp-create-socket@0.2.0-rc-2023-11-10; - import wasi:sockets/udp@0.2.0-rc-2023-11-10; - import wasi:random/random@0.2.0-rc-2023-11-10; - import wasi:random/insecure@0.2.0-rc-2023-11-10; - import wasi:random/insecure-seed@0.2.0-rc-2023-11-10; - import wasi:io/poll@0.2.0-rc-2023-11-10; - import wasi:io/streams@0.2.0-rc-2023-11-10; - - import environment; - import exit; - import stdin; - import stdout; - import stderr; - import terminal-input; - import terminal-output; - import terminal-stdin; - import terminal-stdout; - import terminal-stderr; -}- option<own<
-terminal-output>>