diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 89f7521..6f47982 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -20,4 +20,5 @@ jobs: git diff --exit-code - uses: WebAssembly/wit-abi-up-to-date@v16 with: - worlds: "command reactor" + wit-bindgen: '0.15.0' + worlds: "command imports" diff --git a/command.md b/command.md index dda65a8..4d7f98f 100644 --- a/command.md +++ b/command.md @@ -2,33 +2,33 @@
wasi:clocks/wall-clock@0.2.0-rc-2023-11-10
wasi:io/poll@0.2.0-rc-2023-11-10
wasi:clocks/monotonic-clock@0.2.0-rc-2023-11-10
wasi:cli/environment@0.2.0-rc-2023-11-10
wasi:cli/exit@0.2.0-rc-2023-11-10
wasi:io/error@0.2.0-rc-2023-11-10
wasi:io/poll@0.2.0-rc-2023-11-10
wasi:io/streams@0.2.0-rc-2023-11-10
wasi:cli/stdin@0.2.0-rc-2023-11-10
wasi:cli/stdout@0.2.0-rc-2023-11-10
wasi:cli/stderr@0.2.0-rc-2023-11-10
wasi:cli/terminal-input@0.2.0-rc-2023-11-10
wasi:cli/terminal-output@0.2.0-rc-2023-11-10
wasi:cli/terminal-stdin@0.2.0-rc-2023-11-10
wasi:cli/terminal-stdout@0.2.0-rc-2023-11-10
wasi:cli/terminal-stderr@0.2.0-rc-2023-11-10
wasi:clocks/monotonic-clock@0.2.0-rc-2023-11-10
wasi:clocks/wall-clock@0.2.0-rc-2023-11-10
wasi:filesystem/types@0.2.0-rc-2023-11-10
wasi:filesystem/preopens@0.2.0-rc-2023-11-10
wasi:sockets/network@0.2.0-rc-2023-11-10
wasi:sockets/instance-network@0.2.0-rc-2023-11-10
wasi:sockets/ip-name-lookup@0.2.0-rc-2023-11-10
wasi:sockets/tcp@0.2.0-rc-2023-11-10
wasi:sockets/tcp-create-socket@0.2.0-rc-2023-11-10
wasi:sockets/udp@0.2.0-rc-2023-11-10
wasi:sockets/udp-create-socket@0.2.0-rc-2023-11-10
wasi:sockets/tcp@0.2.0-rc-2023-11-10
wasi:sockets/tcp-create-socket@0.2.0-rc-2023-11-10
wasi:sockets/ip-name-lookup@0.2.0-rc-2023-11-10
wasi:random/random@0.2.0-rc-2023-11-10
wasi:random/insecure@0.2.0-rc-2023-11-10
wasi:random/insecure-seed@0.2.0-rc-2023-11-10
wasi:cli/environment@0.2.0-rc-2023-11-10
wasi:cli/exit@0.2.0-rc-2023-11-10
wasi:cli/stdin@0.2.0-rc-2023-11-10
wasi:cli/stdout@0.2.0-rc-2023-11-10
wasi:cli/stderr@0.2.0-rc-2023-11-10
wasi:cli/terminal-input@0.2.0-rc-2023-11-10
wasi:cli/terminal-output@0.2.0-rc-2023-11-10
wasi:cli/terminal-stdin@0.2.0-rc-2023-11-10
wasi:cli/terminal-stdout@0.2.0-rc-2023-11-10
wasi:cli/terminal-stderr@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.
+record datetime
A time and date in seconds plus nanoseconds.
-get-environment: func
Get 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
: u64
nanoseconds
: u32
string
, string
)>get-arguments: func
Get the POSIX-style arguments to the program.
+initial-cwd: func
Return a path that programs should use as their initial current working
+directory, interpreting .
as shorthand for this.
now: func
Read the current value of the clock.
-This clock is not monotonic, therefore calling this function repeatedly -will not necessarily produce a sequence of non-decreasing values.
-The returned timestamps represent the number of seconds since -1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, -also known as Unix Time.
-The nanoseconds field of the output is always less than 1000000000.
-exit: func
Exit the current instance and any linked instances.
+resource error
A resource which represents some error information.
+The only method provided by this resource is to-debug-string
,
+which provides some human-readable information about the error.
In the wasi:io
package, this resource is returned through the
+wasi:io/streams/stream-error
type.
To provide more specific error information, other interfaces may
+provide functions to further "downcast" this error into more specific
+error information. For example, error
s returned in streams derived
+from filesystem types to be described using the filesystem's own
+error-code type, using the function
+wasi:filesystem/types/filesystem-error-code
, which takes a parameter
+borrow<error>
and returns
+option<wasi:filesystem/types/error-code>
.
error
into a more
+concrete type is open.[method]error.to-debug-string: func
Returns a string that is suitable to assist humans in debugging +this error.
+WARNING: The returned string should not be consumed mechanically! +It may change across platforms, hosts, or other implementation +details. Parsing this string is a major platform-compatibility +hazard.
+resolution: func
Query the resolution of the clock.
-The nanoseconds field of the output is always less than 1000000000.
datetime
string
A poll API intended to let users wait for I/O events on multiple handles @@ -84,7 +114,7 @@ at once.
resource pollable
pollable
represents a single I/O event which may be ready, or not.[method]pollable.ready: func
Return 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 duration
u64
A duration of time, in nanoseconds. -
now: func
Read the current value of the clock.
-The clock is monotonic, therefore calling this function repeatedly will -produce a sequence of non-decreasing values.
-instant
resolution: func
Query the resolution of the clock. Returns the duration of time -corresponding to a clock tick.
-duration
subscribe-instant: func
Create a pollable
which will resolve once the specified instant
-occured.
pollable
>subscribe-duration: func
Create a pollable
which will resolve once the given duration has
-elapsed, starting at the time at which this function was called.
-occured.
pollable
>resource error
[method]error.to-debug-string: func
Returns a string that is suitable to assist humans in debugging -this error.
-WARNING: The returned string should not be consumed mechanically! -It may change across platforms, hosts, or other implementation -details. Parsing this string is a major platform-compatibility -hazard.
-WASI I/O is an I/O abstraction API which is currently focused on providing stream types.
@@ -240,8 +188,21 @@ future operations.resource input-stream
An input bytestream.
+input-stream
s 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-stream
An output bytestream.
+output-stream
s 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: func
Perform 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
@@ -431,7 +392,7 @@ all derived pollable
s created with this fun
[method]output-stream.write-zeroes: func
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.
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
@@ -513,48 +474,250 @@ is ready for reading, before performing the 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 string
s, 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: func
input-stream
>type output-stream
-#### `type datetime` -[`datetime`](#datetime) +---- +
get-stdout: func
output-stream
>type output-stream
-#### `type filesize` -`u64` -
File size or length of a region within a file. -
enum descriptor-type
The type of a filesystem object referenced by a descriptor.
-Note: This was called filetype
in earlier versions of WASI.
get-stderr: func
output-stream
>resource terminal-input
The input side of a terminal.
+resource terminal-output
The 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: func
If 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: func
If 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: func
If 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 duration
u64
A duration of time, in nanoseconds. +
now: func
Read the current value of the clock.
+The clock is monotonic, therefore calling this function repeatedly will +produce a sequence of non-decreasing values.
+instant
resolution: func
Query the resolution of the clock. Returns the duration of time +corresponding to a clock tick.
+duration
subscribe-instant: func
Create a pollable
which will resolve once the specified instant
+occured.
pollable
>subscribe-duration: func
Create a pollable
which will resolve once the given duration has
+elapsed, starting at the time at which this function was called.
+occured.
pollable
>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 datetime
A time and date in seconds plus nanoseconds.
+seconds
: u64
nanoseconds
: u32
now: func
Read the current value of the clock.
+This clock is not monotonic, therefore calling this function repeatedly +will not necessarily produce a sequence of non-decreasing values.
+The returned timestamps represent the number of seconds since +1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, +also known as Unix Time.
+The nanoseconds field of the output is always less than 1000000000.
+datetime
resolution: func
Query the resolution of the clock.
+The nanoseconds field of the output is always less than 1000000000.
+datetime
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 string
s, 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-type
The 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 descriptor
A 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: func
Return a stream for reading from a file, if available.
@@ -1408,6 +1574,9 @@ errors are filesystem-related errors.resource network
An opaque resource that represents access to (a subset of) the network. +This enables context-based security for networking. +There is no need for this to map 1:1 to a physical network interface.
enum error-code
Error 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: func
Resolve an internet host name to a list of IP addresses.
-Unicode domain names are automatically converted to ASCII using IDNA encoding. -If the input is an IP address string, the address is parsed and returned -as-is without making any external requests.
-See the wasi-socket proposal README.md for a comparison with getaddrinfo.
-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-datagram
A datagram to be sent out.
+resolve-address-stream
>, error-code
>[method]resolve-address-stream.resolve-next-address: func
Returns the next address from the resolver.
-This function should be called multiple times. On each call, it will
-return the next address in connection order preference. If all
-addresses have been exhausted, this function returns none
.
This function never returns IPv4-mapped IPv6 addresses.
-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: func
Create a pollable
which will resolve once the stream is ready for I/O.
Note: this function is here for WASI Preview2 only.
-It's planned to be removed when future
is natively supported in Preview3.
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-socket
resource udp-socket
A UDP socket handle.
+resource incoming-datagram-stream
resource outgoing-datagram-stream
[method]tcp-socket.start-bind: func
[method]udp-socket.start-bind: func
Bind the socket to a specific network on the provided IP address and port.
If the IP address is zero (0.0.0.0
in IPv4, ::
in IPv6), it is left to the implementation to decide which
network interface(s) to bind to.
-If the TCP/UDP port is zero, the socket will be bound to a random free port.
When a socket is not explicitly bound, the first invocation to 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-address
self
: borrow<udp-socket
>network
: borrow<network
>local-address
: ip-socket-address
error-code
>error-code
>[method]tcp-socket.finish-bind: func
[method]udp-socket.finish-bind: func
self
: borrow<tcp-socket
>self
: borrow<udp-socket
>error-code
>[method]tcp-socket.start-connect: func
Connect 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: func
Set up inbound & outbound communication channels, optionally to a specific peer.
+This function only changes the local socket configuration and does not generate any network traffic.
+On success, the remote-address
of the socket is updated. The local-address
may be updated as well,
+based on the best network path to remote-address
.
When a remote-address
is provided, the returned streams are limited to communicating with that specific peer:
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-address
self
: 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: func
Get the current bound address.
+POSIX mentions:
+++If the socket has not been bound to a local name, the value +stored in the object pointed to by
+address
is unspecified.
WASI is stricter and requires local-address
to return invalid-state
when the socket hasn't been bound yet.
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: func
Start 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: func
Get 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: func
Whether 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: func
Accept 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: func
Whether IPv4 compatibility (dual-stack) mode is disabled or not.
+Equivalent to the IPV6_V6ONLY socket option.
+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) 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: func
self
: borrow<tcp-socket
>self
: borrow<udp-socket
>value
: bool
tcp-socket
>, own<input-stream
>, own<output-stream
>), error-code
>error-code
>[method]tcp-socket.local-address: func
Get the bound local address.
-POSIX mentions:
---If the socket has not been bound to a local name, the value -stored in the object pointed to by
-address
is unspecified.
WASI is stricter and requires local-address
to return invalid-state
when the socket hasn't been bound yet.
[method]udp-socket.unicast-hop-limit: func
Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+If the provided value is 0, an invalid-argument
error is returned.
invalid-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: func
self
: borrow<tcp-socket
>self
: borrow<udp-socket
>value
: u8
ip-socket-address
, error-code
>error-code
>[method]tcp-socket.remote-address: func
Get the remote address.
+[method]udp-socket.receive-buffer-size: func
The 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: func
Whether the socket is listening for new connections.
-Equivalent to the SO_ACCEPTCONN socket option.
+[method]udp-socket.set-receive-buffer-size: func
self
: borrow<tcp-socket
>self
: borrow<udp-socket
>value
: u64
bool
error-code
>[method]tcp-socket.address-family: func
Whether this is a IPv4 or IPv6 socket.
-Equivalent to the SO_DOMAIN socket option.
+[method]udp-socket.send-buffer-size: func
self
: borrow<tcp-socket
>self
: borrow<udp-socket
>[method]tcp-socket.ipv6-only: func
Whether 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: func
self
: borrow<tcp-socket
>self
: borrow<udp-socket
>value
: u64
bool
, error-code
>error-code
>[method]tcp-socket.set-ipv6-only: func
[method]udp-socket.subscribe: func
Create a pollable
which will resolve once the socket is ready for I/O.
Note: this function is here for WASI Preview2 only.
+It's planned to be removed when future
is natively supported in Preview3.
self
: borrow<tcp-socket
>value
: bool
self
: borrow<udp-socket
>error-code
>pollable
>[method]incoming-datagram-stream.receive: func
Receive messages on the socket.
+This function attempts to receive up to max-results
datagrams on the socket without blocking.
+The returned list may contain fewer elements than requested, but never more.
This function returns successfully with an empty list when either:
+max-results
is 0, or:max-results
is greater than 0, but no results are immediately available.
+This function never returns error(would-block)
.[method]tcp-socket.set-listen-backlog-size: func
Hints the desired listen queue size. Implementations are free to ignore this.
-If the provided value is 0, an invalid-argument
error is returned.
-Any other value will never cause an error, but it might be silently clamped and/or rounded.
not-supported
: (set) The platform does not support changing the backlog size after the initial listen.invalid-argument
: (set) The provided value was 0.invalid-state
: (set) The socket is already in the Connection state.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
: u64
error-code
>self
: borrow<incoming-datagram-stream
>max-results
: u64
[method]tcp-socket.keep-alive-enabled: func
Enables or disables keepalive.
-The keepalive behavior can be adjusted using:
+keep-alive-idle-time
keep-alive-interval
keep-alive-count
-These properties can be configured while keep-alive-enabled
is false, but only come into effect when keep-alive-enabled
is true.incoming-datagram
>, error-code
>Equivalent to the SO_KEEPALIVE socket option.
+[method]incoming-datagram-stream.subscribe: func
Create a pollable
which will resolve once the stream is ready to receive again.
Note: this function is here for WASI Preview2 only.
+It's planned to be removed when future
is natively supported in Preview3.
self
: borrow<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: func
Check readiness for sending. This function never blocks.
+Returns the number of datagrams permitted for the next call to send
,
+or an error. Calling send
with more datagrams than this function has
+permitted will trap.
When this function returns ok(0), the subscribe
pollable will
+become ready when this function will report at least ok(1), or an
+error.
Never returns would-block
.
self
: borrow<tcp-socket
>value
: bool
self
: borrow<outgoing-datagram-stream
>error-code
>u64
, error-code
>[method]tcp-socket.keep-alive-idle-time: func
Amount of time the connection has to be idle before TCP starts sending keepalive packets.
-If the provided value is 0, an invalid-argument
error is returned.
-Any other value will never cause an error, but it might be silently clamped and/or rounded.
-I.e. after setting a value, reading the same setting back may return a different value.
Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)
+[method]outgoing-datagram-stream.send: func
Send messages on the socket.
+This function attempts to send all provided datagrams
on the socket without blocking and
+returns how many messages were actually sent (or queued for sending). This function never
+returns error(would-block)
. If none of the datagrams were able to be sent, ok(0)
is returned.
This function semantically behaves the same as iterating the datagrams
list and sequentially
+sending each individual datagram until either the end of the list has been reached or the first error occurred.
+If at least one datagram has been sent successfully, this function never returns an error.
If the input list is empty, the function returns ok(0)
.
Each call to send
must be permitted by a preceding check-send
. Implementations must trap if
+either check-send
was not called or datagrams
contains more items than check-send
permitted.
invalid-argument
: (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: func
self
: borrow<tcp-socket
>value
: duration
self
: borrow<outgoing-datagram-stream
>datagrams
: list<outgoing-datagram
>error-code
>[method]tcp-socket.keep-alive-interval: func
The time between keepalive packets.
-If the provided value is 0, an invalid-argument
error is returned.
-Any other value will never cause an error, but it might be silently clamped and/or rounded.
-I.e. after setting a value, reading the same setting back may return a different value.
Equivalent to the TCP_KEEPINTVL socket option.
-invalid-argument
: (set) The provided value was 0.u64
, error-code
>[method]outgoing-datagram-stream.subscribe: func
Create a pollable
which will resolve once the stream is ready to send again.
Note: this function is here for WASI Preview2 only.
+It's planned to be removed when future
is natively supported in Preview3.
self
: borrow<tcp-socket
>self
: borrow<outgoing-datagram-stream
>duration
, error-code
>pollable
>[method]tcp-socket.set-keep-alive-interval: func
self
: borrow<tcp-socket
>value
: duration
error-code
>[method]tcp-socket.keep-alive-count: func
The maximum amount of keepalive packets TCP should send before aborting the connection.
-If the provided value is 0, an invalid-argument
error is returned.
-Any other value will never cause an error, but it might be silently clamped and/or rounded.
-I.e. after setting a value, reading the same setting back may return a different value.
Equivalent to the TCP_KEEPCNT socket option.
-invalid-argument
: (set) The provided value was 0.self
: borrow<tcp-socket
>u32
, error-code
>[method]tcp-socket.set-keep-alive-count: func
self
: borrow<tcp-socket
>value
: u32
error-code
>[method]tcp-socket.hop-limit: func
Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
-If the provided value is 0, an invalid-argument
error is returned.
invalid-argument
: (set) The TTL value must be 1 or higher.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: func
self
: borrow<tcp-socket
>value
: u8
error-code
>[method]tcp-socket.receive-buffer-size: func
The 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: func
self
: borrow<tcp-socket
>value
: u64
error-code
>[method]tcp-socket.send-buffer-size: func
self
: borrow<tcp-socket
>u64
, error-code
>[method]tcp-socket.set-send-buffer-size: func
self
: borrow<tcp-socket
>value
: u64
error-code
>[method]tcp-socket.subscribe: func
Create a pollable
which will resolve once the socket is ready for I/O.
Note: this function is here for WASI Preview2 only.
-It's planned to be removed when future
is natively supported in Preview3.
self
: borrow<tcp-socket
>pollable
>[method]tcp-socket.shutdown: func
Initiate 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-type
error-code
>type network
output-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: func
Create a new TCP socket.
-Similar to socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP)
in POSIX.
create-udp-socket: func
Create a new UDP socket.
+Similar to socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP)
in POSIX.
This function does not require a network capability handle. This is considered to be safe because
-at time of creation, the socket is not bound to any network
yet. Up to the moment bind
/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 pollable
type 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-datagram
A 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-socket
resource incoming-datagram-stream
resource outgoing-datagram-stream
resource tcp-socket
[method]udp-socket.start-bind: func
[method]tcp-socket.start-bind: func
Bind the socket to a specific network on the provided IP address and port.
If the IP address is zero (0.0.0.0
in IPv4, ::
in IPv6), it is left to the implementation to decide which
network interface(s) to bind to.
-If the 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-address
self
: borrow<tcp-socket
>network
: borrow<network
>local-address
: ip-socket-address
error-code
>error-code
>[method]udp-socket.finish-bind: func
[method]tcp-socket.finish-bind: func
self
: borrow<udp-socket
>self
: borrow<tcp-socket
>error-code
>error-code
>[method]udp-socket.stream: func
Set up inbound & outbound communication channels, optionally to a specific peer.
-This function only changes the local socket configuration and does not generate any network traffic.
-On success, the remote-address
of the socket is updated. The local-address
may be updated as well,
-based on the best network path to remote-address
.
When a remote-address
is provided, the returned streams are limited to communicating with that specific peer:
[method]tcp-socket.start-connect: func
Connect 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-address
incoming-datagram-stream
>, own<outgoing-datagram-stream
>), error-code
>error-code
>[method]udp-socket.local-address: func
Get the current bound address.
+[method]tcp-socket.finish-connect: func
self
: borrow<tcp-socket
>input-stream
>, own<output-stream
>), error-code
>[method]tcp-socket.start-listen: func
Start 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: func
self
: borrow<tcp-socket
>error-code
>[method]tcp-socket.accept: func
Accept 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-size
On success, this function returns the newly accepted client socket along with +a pair of streams that can be used to read & write to the connection.
+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: func
Get 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
address
is 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: func
Get 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: func
Whether 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: func
Whether 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: func
Whether 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)this
socket 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: func
Params
++
+- +
self
: borrow<tcp-socket
>- +
value
:bool
Return values
++
+- result<_,
+error-code
>+
[method]tcp-socket.set-listen-backlog-size: func
Hints the desired listen queue size. Implementations are free to ignore this.
+If the provided value is 0, an
+invalid-argument
error is returned. +Any other value will never cause an error, but it might be silently clamped and/or rounded.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
:u64
Return values
-
-- result<
-ip-socket-address
,error-code
>-
[method]udp-socket.remote-address: func
Get 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: func
Enables 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-interval
keep-alive-count
+These properties can be configured whilekeep-alive-enabled
is false, but only come into effect whenkeep-alive-enabled
is 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: func
Whether this is a IPv4 or IPv6 socket.
-Equivalent to the SO_DOMAIN socket option.
+
[method]tcp-socket.set-keep-alive-enabled: func
Params
-
- +
self
: borrow<udp-socket
>- +
self
: borrow<tcp-socket
>value
:bool
Return values
-
-- +
ip-address-family
- result<_,
error-code
>-
[method]udp-socket.ipv6-only: func
Whether IPv4 compatibility (dual-stack) mode is disabled or not.
-Equivalent to the IPV6_V6ONLY socket option.
++
[method]tcp-socket.keep-alive-idle-time: func
Amount of time the connection has to be idle before TCP starts sending keepalive packets.
+If the provided value is 0, an
+invalid-argument
error is returned. +Any other value will never cause an error, but it might be silently clamped and/or rounded. +I.e. after setting a value, reading the same setting back may return a different value.Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)
Typical errors
-
- -
not-supported
: (get/set)this
socket is an IPv4 socket.- -
invalid-state
: (set) The socket is already bound.- +
not-supported
: (set) Host does not support dual-stack sockets. (Implementations are not required to.)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: func
Params
-
- -
self
: borrow<udp-socket
>- +
value
:bool
- +
self
: borrow<tcp-socket
>value
:duration
Return values
-
-- result<_,
+error-code
>- result<_,
error-code
>-
[method]udp-socket.unicast-hop-limit: func
Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
-If the provided value is 0, an
+invalid-argument
error is returned.+
[method]tcp-socket.keep-alive-interval: func
The time between keepalive packets.
+If the provided value is 0, an
+invalid-argument
error is returned. +Any other value will never cause an error, but it might be silently clamped and/or rounded. +I.e. after setting a value, reading the same setting back may return a different value.Equivalent to the TCP_KEEPINTVL socket option.
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: func
Params
-
- -
self
: borrow<udp-socket
>- +
value
:u8
- +
self
: borrow<tcp-socket
>value
:duration
Return values
-
-- result<_,
+error-code
>- result<_,
error-code
>-
[method]udp-socket.receive-buffer-size: func
The kernel buffer space reserved for sends/receives on this socket.
++
[method]tcp-socket.keep-alive-count: func
The maximum amount of keepalive packets TCP should send before aborting the connection.
If the provided value is 0, an
-invalid-argument
error is returned. Any other value will never cause an error, but it might be silently clamped and/or rounded. I.e. after setting a value, reading the same setting back may return a different value.Equivalent to the 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: func
Params
-
- -
self
: borrow<udp-socket
>- +
value
:u64
- +
self
: borrow<tcp-socket
>value
:u32
Return values
-
-- result<_,
-error-code
>-
[method]udp-socket.send-buffer-size: func
Params
--
-- +
self
: borrow<udp-socket
>- result<_,
error-code
>Return values
++
[method]tcp-socket.hop-limit: func
Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+If the provided value is 0, an
+invalid-argument
error is returned.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: func
Params
-
- -
self
: borrow<udp-socket
>- +
value
:u64
self
: borrow<tcp-socket
>Return values
-
-- result<_,
+error-code
>- result<
u8
,error-code
>-
[method]udp-socket.subscribe: func
Create a
-pollable
which will resolve once the socket is ready for I/O.Note: this function is here for WASI Preview2 only. -It's planned to be removed when
+future
is natively supported in Preview3.
[method]tcp-socket.set-hop-limit: func
Params
-
- +
self
: borrow<udp-socket
>- +
self
: borrow<tcp-socket
>value
:u8
Return values
-
-- own<
+pollable
>- result<_,
error-code
>-
[method]incoming-datagram-stream.receive: func
Receive messages on the socket.
-This function attempts to receive up to
-max-results
datagrams on the socket without blocking. -The returned list may contain fewer elements than requested, but never more.This function returns successfully with an empty list when either:
++
[method]tcp-socket.receive-buffer-size: func
The 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.
+Typical errors
-
-- -
max-results
is 0, or:- +
max-results
is 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: func
Params
-
- -
self
: borrow<incoming-datagram-stream
>- +
max-results
:u64
- +
self
: borrow<tcp-socket
>value
:u64
Return values
-
-- result<list<
+incoming-datagram
>,error-code
>- result<_,
error-code
>-
[method]incoming-datagram-stream.subscribe: func
Create a
-pollable
which will resolve once the stream is ready to receive again.Note: this function is here for WASI Preview2 only. -It's planned to be removed when
+future
is natively supported in Preview3.
[method]tcp-socket.send-buffer-size: func
Params
-
- +
self
: borrow<incoming-datagram-stream
>self
: borrow<tcp-socket
>Return values
-
-- own<
+pollable
>- result<
u64
,error-code
>-
[method]outgoing-datagram-stream.check-send: func
Check readiness for sending. This function never blocks.
-Returns the number of datagrams permitted for the next call to
-send
, -or an error. Callingsend
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
.
[method]tcp-socket.set-send-buffer-size: func
Params
-
- +
self
: borrow<outgoing-datagram-stream
>- +
self
: borrow<tcp-socket
>value
:u64
Return values
-
-- result<
+u64
,error-code
>- result<_,
error-code
>-
[method]outgoing-datagram-stream.send: func
Send messages on the socket.
-This function attempts to send all provided
-datagrams
on the socket without blocking and -returns how many messages were actually sent (or queued for sending). This function never -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
-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 precedingcheck-send
. Implementations must trap if -eithercheck-send
was not called ordatagrams
contains more items thancheck-send
permitted.Typical errors
++
[method]tcp-socket.subscribe: func
Create a
+pollable
which will resolve once the socket is ready for I/O.Note: this function is here for WASI Preview2 only. +It's planned to be removed when
+future
is natively supported in Preview3.Params
-
-- -
invalid-argument
: Theremote-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 inremote-address
is set to INADDR_ANY (0.0.0.0
/::
). (EDESTADDRREQ, EADDRNOTAVAIL)- -
invalid-argument
: The port inremote-address
is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)- -
invalid-argument
: The socket is in "connected" mode andremote-address
issome
value that does not match the address passed tostream
. (EISCONN)- -
invalid-argument
: The socket is not "connected" and no value forremote-address
was provided. (EDESTADDRREQ)- -
remote-unreachable
: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)- -
connection-refused
: The connection was refused. (ECONNREFUSED)- +
datagram-too-large
: The datagram is too large. (EMSGSIZE)self
: borrow<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: func
Initiate a graceful shutdown.
++
+- receive: the socket is not expecting to receive any more data from the peer. All subsequent read +operations on the
+input-stream
associated with this socket will return an End Of Stream indication. +Any data still in the receive queue at time of callingshutdown
will be discarded.- send: the socket is not expecting to send any more data to the peer. All subsequent write +operations on the
+output-stream
associated with this socket will return an error.- both: same effect as receive & send combined.
+The shutdown function does not close (drop) the socket.
+Typical errors
-
-- -
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: func
Create a
-pollable
which will resolve once the stream is ready to send again.Note: this function is here for WASI Preview2 only. -It's planned to be removed when
future
is natively supported in Preview3.Params
-
- +
self
: borrow<outgoing-datagram-stream
>- +
self
: borrow<tcp-socket
>shutdown-type
:shutdown-type
Return 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 network
future
is 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: func
Create a new UDP socket.
-Similar to
+socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP)
in POSIX.+
create-tcp-socket: func
Create a new TCP socket.
+Similar to
socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP)
in POSIX.This function does not require a network capability handle. This is considered to be safe because -at time of creation, the socket is not bound to any
+at time of creation, the socket is not bound to anynetwork
yet. Up to the momentbind
is called, -the socket is effectively an in-memory configuration object, unable to communicate with the outside world.network
yet. 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-family
is 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: func
Resolve an internet host name to a list of IP addresses.
+Unicode domain names are automatically converted to ASCII using IDNA encoding. +If the input is an IP address string, the address is parsed and returned +as-is without making any external requests.
+See the wasi-socket proposal README.md for a comparison with getaddrinfo.
+This function never blocks. It either immediately fails or immediately +returns successfully with a
+resolve-address-stream
that can be used +to (asynchronously) fetch the results.Typical errors
++
+- +
invalid-argument
:name
is 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: func
Returns the next address from the resolver.
+This function should be called multiple times. On each call, it will +return the next address in connection order preference. If all +addresses have been exhausted, this function returns
+none
.This function never returns IPv4-mapped IPv6 addresses.
+Typical errors
++
+- +
name-unresolvable
: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)- +
temporary-resolver-failure
: A temporary failure in name resolution occurred. (EAI_AGAIN)- +
permanent-resolver-failure
: A permanent failure in name resolution occurred. (EAI_FAIL)- +
would-block
: A result is not available yet. (EWOULDBLOCK, EAGAIN)Params
++
+- +
self
: borrow<resolve-address-stream
>Return values
++
+- result<option<
+ip-address
>,error-code
>+
[method]resolve-address-stream.subscribe: func
Create a
+pollable
which will resolve once the stream is ready for I/O.Note: this function is here for WASI Preview2 only. +It's planned to be removed when
+future
is natively supported in Preview3.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: func
Get 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: func
Get the POSIX-style arguments to the program.
-Return values
- --
initial-cwd: func
Return 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: func
Exit 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: func
Return values
--
-- own<
-input-stream
>Import interface wasi:cli/stdout@0.2.0-rc-2023-11-10
-
-Types
-- -
type output-stream
----- -
Functions
--
get-stdout: func
Return values
--
-- own<
-output-stream
>Import interface wasi:cli/stderr@0.2.0-rc-2023-11-10
-
-Types
-- -
type output-stream
----- -
Functions
--
get-stderr: func
Return values
--
-- own<
-output-stream
>Import interface wasi:cli/terminal-input@0.2.0-rc-2023-11-10
-
-Types
--
resource terminal-input
Import interface wasi:cli/terminal-output@0.2.0-rc-2023-11-10
-
-Types
--
resource terminal-output
Import interface wasi:cli/terminal-stdin@0.2.0-rc-2023-11-10
-An interface providing an optional
-terminal-input
for stdin as a -link-time authority.
-Types
-- -
type terminal-input
----- -
Functions
--
get-terminal-stdin: func
If stdin is connected to a terminal, return a
-terminal-input
handle -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-output
for stdout as a -link-time authority.
-Types
-- -
type terminal-output
----- -
Functions
--
get-terminal-stdout: func
If stdout is connected to a terminal, return a
-terminal-output
handle -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-output
for stderr as a -link-time authority.
-Types
-- -
type terminal-output
----- -
Functions
--
get-terminal-stderr: func
If stderr is connected to a terminal, return a
-terminal-output
handle -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-10
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.
+Import interface wasi:cli/environment@0.2.0-rc-2023-11-10
-Types
--
record datetime
A time and date in seconds plus nanoseconds.
-Record Fields
+Functions
++
get-environment: func
Get 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: func
Get the POSIX-style arguments to the program.
+Return values
+ ++
initial-cwd: func
Return 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: func
Read the current value of the clock.
-This clock is not monotonic, therefore calling this function repeatedly -will not necessarily produce a sequence of non-decreasing values.
-The returned timestamps represent the number of seconds since -1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, -also known as Unix Time.
-The nanoseconds field of the output is always less than 1000000000.
-Return values
++
exit: func
Exit the current instance and any linked instances.
+Params
+Import interface wasi:io/error@0.2.0-rc-2023-11-10
+
+Types
++
resource error
A resource which represents some error information.
+The only method provided by this resource is
+to-debug-string
, +which provides some human-readable information about the error.In the
+wasi:io
package, this resource is returned through the +wasi:io/streams/stream-error
type.To provide more specific error information, other interfaces may +provide functions to further "downcast" this error into more specific +error information. For example,
+error
s returned in streams derived +from filesystem types to be described using the filesystem's own +error-code type, using the function +wasi:filesystem/types/filesystem-error-code
, which takes a parameter +borrow<error>
and returns +option<wasi:filesystem/types/error-code>
.The set of functions which can "downcast" an
+error
into a more +concrete type is open.Functions
++
[method]error.to-debug-string: func
Returns a string that is suitable to assist humans in debugging +this error.
+WARNING: The returned string should not be consumed mechanically! +It may change across platforms, hosts, or other implementation +details. Parsing this string is a major platform-compatibility +hazard.
+Params
+ --
resolution: func
Query the resolution of the clock.
-The nanoseconds field of the output is always less than 1000000000.
Return values
-
- +
datetime
string
Import 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
+
pollable
represents a single I/O event which may be ready, or not.Functions
[method]pollable.ready: func
Return 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
-
u64
A duration of time, in nanoseconds. -
-Functions
--
now: func
Read the current value of the clock.
-The clock is monotonic, therefore calling this function repeatedly will -produce a sequence of non-decreasing values.
-Return values
--
-- -
instant
-
resolution: func
Query the resolution of the clock. Returns the duration of time -corresponding to a clock tick.
-Return values
--
-- -
duration
-
subscribe-instant: func
Create a
-pollable
which will resolve once the specified instant -occured.Params
- -Return values
--
-- own<
-pollable
>-
subscribe-duration: func
Create a
-pollable
which will resolve once the given duration has -elapsed, starting at the time at which this function was called. -occured.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: func
Returns a string that is suitable to assist humans in debugging -this error.
-WARNING: The returned string should not be consumed mechanically! -It may change across platforms, hosts, or other implementation -details. Parsing this string is a major platform-compatibility -hazard.
-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-stream
An input bytestream.
+
input-stream
s 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 thesubscribe
function to obtain apollable
which can be polled +for usingwasi:io/poll
.-
resource output-stream
+An output bytestream.
+
output-stream
s 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, thesubscribe
function to obtain apollable
which can be +polled for usingwasi:io/poll
.Functions
[method]input-stream.read: func
Perform 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 handling
pollable
s created with this fun
[method]output-stream.write-zeroes: func
Write zeroes to a stream.
-this should be used precisely like
write
with the exact same +This should be used precisely like
@@ -449,7 +410,7 @@ the following pseudo-code: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.@@ -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 handling
splice
.-
- 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
-string
s, 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 apath
argument 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: func
Return 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: func
Return 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-type
The type of a filesystem object referenced by a descriptor.
-Note: This was called
-filetype
in earlier versions of WASI.Enum Cases
+---- +Functions
++
get-stderr: func
Return values
-
+- - +
- own<
+output-stream
>Import interface wasi:cli/terminal-input@0.2.0-rc-2023-11-10
+
+Types
++
resource terminal-input
The input side of a terminal.
+Import interface wasi:cli/terminal-output@0.2.0-rc-2023-11-10
+
+Types
++
resource terminal-output
The output side of a terminal.
+Import interface wasi:cli/terminal-stdin@0.2.0-rc-2023-11-10
+An interface providing an optional
+terminal-input
for stdin as a +link-time authority.
+Types
++ +
type terminal-input
+---- +
Functions
++
get-terminal-stdin: func
If stdin is connected to a terminal, return a
+terminal-input
handle +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-output
for stdout as a +link-time authority.
+Types
++ +
type terminal-output
+---- +
Functions
++
get-terminal-stdout: func
If stdout is connected to a terminal, return a
+terminal-output
handle +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-output
for stderr as a +link-time authority.
+Types
++ +
type terminal-output
+---- +
Functions
++
get-terminal-stderr: func
If stderr is connected to a terminal, return a
+terminal-output
handle +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
+
u64
A duration of time, in nanoseconds. +
+Functions
++
now: func
Read the current value of the clock.
+The clock is monotonic, therefore calling this function repeatedly will +produce a sequence of non-decreasing values.
+Return values
++
+- +
instant
+
resolution: func
Query the resolution of the clock. Returns the duration of time +corresponding to a clock tick.
+Return values
++
+- +
duration
+
subscribe-instant: func
Create a
+pollable
which will resolve once the specified instant +occured.Params
+ +Return values
++
+- own<
+pollable
>+
subscribe-duration: func
Create a
+pollable
which will resolve once the given duration has +elapsed, starting at the time at which this function was called. +occured.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 datetime
A time and date in seconds plus nanoseconds.
+Record Fields
++
+- +
seconds
:u64
- +
nanoseconds
:u32
+Functions
++
now: func
Read the current value of the clock.
+This clock is not monotonic, therefore calling this function repeatedly +will not necessarily produce a sequence of non-decreasing values.
+The returned timestamps represent the number of seconds since +1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, +also known as Unix Time.
+The nanoseconds field of the output is always less than 1000000000.
+Return values
++
+- +
datetime
+
resolution: func
Query the resolution of the clock.
+The nanoseconds field of the output is always less than 1000000000.
+Return values
++
+- +
datetime
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
+string
s, 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 apath
argument 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-type
The type of a filesystem object referenced by a descriptor.
+Note: This was called
+filetype
in 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 descriptor
A 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: func
Return a stream for reading from a file, if available.
@@ -1403,6 +1569,9 @@ errors are filesystem-related errors.
Types
+
resource network
An opaque resource that represents access to (a subset of) the network. +This enables context-based security for networking. +There is no need for this to map 1:1 to a physical network interface.
enum error-code
Error 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: func
Resolve an internet host name to a list of IP addresses.
-Unicode domain names are automatically converted to ASCII using IDNA encoding. -If the input is an IP address string, the address is parsed and returned -as-is without making any external requests.
-See the wasi-socket proposal README.md for a comparison with getaddrinfo.
-This function never blocks. It either immediately fails or immediately -returns successfully with a
-resolve-address-stream
that can be used -to (asynchronously) fetch the results.Typical errors
--
-- -
invalid-argument
:name
is 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-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 ofrecvfrom
.Params
++
record outgoing-datagram
A datagram to be sent out.
+Record Fields
-Return values
--
-- result<own<
-resolve-address-stream
>,error-code
>-
[method]resolve-address-stream.resolve-next-address: func
Returns the next address from the resolver.
-This function should be called multiple times. On each call, it will -return the next address in connection order preference. If all -addresses have been exhausted, this function returns
-none
.This function never returns IPv4-mapped IPv6 addresses.
-Typical errors
--
-- -
name-unresolvable
: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)- -
temporary-resolver-failure
: A temporary failure in name resolution occurred. (EAI_AGAIN)- -
permanent-resolver-failure
: A permanent failure in name resolution occurred. (EAI_FAIL)- -
would-block
: A result is not available yet. (EWOULDBLOCK, EAGAIN)Params
--
-- -
self
: borrow<resolve-address-stream
>Return values
--
-- result<option<
-ip-address
>,error-code
>-
[method]resolve-address-stream.subscribe: func
Create a
-pollable
which will resolve once the stream is ready for I/O.Note: this function is here for WASI Preview2 only. -It's planned to be removed when
-future
is natively supported in Preview3.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
send
in POSIX. Otherwise it is equivalent tosendto
.+
resource tcp-socket
+
resource udp-socket
A UDP socket handle.
++
resource incoming-datagram-stream
resource outgoing-datagram-stream
Functions
-+
[method]tcp-socket.start-bind: func
[method]udp-socket.start-bind: func
Bind the socket to a specific network on the provided IP address and port.
If the IP address is zero (
-0.0.0.0
in IPv4,::
in IPv6), it is left to the implementation to decide which network interface(s) to bind to. -If the TCP/UDP port is zero, the socket will be bound to a random free port.When a socket is not explicitly bound, the first invocation to 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
start
errors
- -
invalid-argument
: Thelocal-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 hasipv6-only
enabled. (EINVAL)invalid-state
: The socket is already bound. (EINVAL)Typical
@@ -1742,63 +1840,55 @@ implicitly bind the socket.finish
errorsParams
-
- -
self
: borrow<tcp-socket
>- -
network
: borrow<network
>- +
local-address
:ip-socket-address
- +
self
: borrow<udp-socket
>- +
network
: borrow<network
>local-address
:ip-socket-address
Return values
-
-- result<_,
+error-code
>- result<_,
error-code
>+
[method]tcp-socket.finish-bind: func
[method]udp-socket.finish-bind: func
Params
-
- +
self
: borrow<tcp-socket
>self
: borrow<udp-socket
>Return values
-
-- result<_,
-error-code
>-
[method]tcp-socket.start-connect: func
Connect to a remote endpoint.
-On success:
--
-- the socket is transitioned into the Connection state
-- a pair of streams is returned that can be used to read & write to the connection
+- 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: func
Set up inbound & outbound communication channels, optionally to a specific peer.
+This function only changes the local socket configuration and does not generate any network traffic. +On success, the
+remote-address
of the socket is updated. Thelocal-address
may be updated as well, +based on the best network path toremote-address
.When a
remote-address
is provided, the returned streams are limited to communicating with that specific peer:-
-- If
-connect
fails because an input/state validation error, the socket should remain usable.- If a connection was actually attempted but failed, the socket should become unusable for further network communication. -Besides
+drop
, any method after such a failure may return an error.- +
send
can only be used to send to this destination.receive
will only return datagrams sent from the providedremote-address
.Typical
+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.
+Typical errors
-
- -
invalid-argument
: Theremote-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 hasipv6-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 inremote-address
is set to INADDR_ANY (0.0.0.0
/::
). (EADDRNOTAVAIL on Windows)- -
invalid-argument
: The port inremote-address
is set to 0. (EADDRNOTAVAIL on Windows)- -
invalid-argument
: The socket is already attached to a different network. Thenetwork
passed toconnect
must 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
-finish
errors-
- -
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-address
is set to INADDR_ANY (0.0.0.0
/::
). (EDESTADDRREQ, EADDRNOTAVAIL)- +
invalid-argument
: The port inremote-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
: Aconnect
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)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: func
Params
++
[method]udp-socket.local-address: func
Get the current bound address.
+POSIX mentions:
+++If the socket has not been bound to a local name, the value +stored in the object pointed to by
+address
is unspecified.WASI is stricter and requires
+local-address
to returninvalid-state
when 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: func
Start 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
+start
errorsReturn 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
+finish
errors+
[method]udp-socket.remote-address: func
Get 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
: Alisten
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)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: func
Whether 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: func
Accept 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: func
Whether 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)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.
-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: func
Params
-
- +
self
: borrow<tcp-socket
>- +
self
: borrow<udp-socket
>value
:bool
Return values
-
-- result<(own<
+tcp-socket
>, own<input-stream
>, own<output-stream
>),error-code
>- result<_,
error-code
>-
[method]tcp-socket.local-address: func
Get the bound local address.
-POSIX mentions:
---If the socket has not been bound to a local name, the value -stored in the object pointed to by
-address
is unspecified.WASI is stricter and requires
+local-address
to returninvalid-state
when the socket hasn't been bound yet.+
[method]udp-socket.unicast-hop-limit: func
Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+If the provided value is 0, an
invalid-argument
error is returned.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: func
Params
-
- +
self
: borrow<tcp-socket
>- +
self
: borrow<udp-socket
>value
:u8
Return values
-
-- result<
+ip-socket-address
,error-code
>- result<_,
error-code
>-
[method]tcp-socket.remote-address: func
Get the remote address.
++
[method]udp-socket.receive-buffer-size: func
The 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.
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: func
Whether the socket is listening for new connections.
-Equivalent to the SO_ACCEPTCONN socket option.
+
[method]udp-socket.set-receive-buffer-size: func
Params
-
- +
self
: borrow<tcp-socket
>- +
self
: borrow<udp-socket
>value
:u64
Return values
-
-- +
bool
- result<_,
error-code
>-
[method]tcp-socket.address-family: func
Whether this is a IPv4 or IPv6 socket.
-Equivalent to the SO_DOMAIN socket option.
+
[method]udp-socket.send-buffer-size: func
Params
-
- +
self
: borrow<tcp-socket
>self
: borrow<udp-socket
>Return values
--
[method]tcp-socket.ipv6-only: func
Whether 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)this
socket 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: func
Params
-
- +
self
: borrow<tcp-socket
>- +
self
: borrow<udp-socket
>value
:u64
Return values
-
-- result<
+bool
,error-code
>- result<_,
error-code
>+
[method]tcp-socket.set-ipv6-only: func
+
[method]udp-socket.subscribe: func
Create a
+pollable
which will resolve once the socket is ready for I/O.Note: this function is here for WASI Preview2 only. +It's planned to be removed when
future
is natively supported in Preview3.Params
-
- -
self
: borrow<tcp-socket
>- +
value
:bool
self
: borrow<udp-socket
>Return values
-
+- result<_,
+error-code
>- own<
+pollable
>+
[method]incoming-datagram-stream.receive: func
Receive messages on the socket.
+This function attempts to receive up to
+max-results
datagrams on the socket without blocking. +The returned list may contain fewer elements than requested, but never more.This function returns successfully with an empty list when either:
++
-- +
max-results
is 0, or:max-results
is greater than 0, but no results are immediately available. +This function never returnserror(would-block)
.-
[method]tcp-socket.set-listen-backlog-size: func
Hints the desired listen queue size. Implementations are free to ignore this.
-If the provided value is 0, an
invalid-argument
error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded.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: func
Enables 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-enabled
is false, but only come into effect whenkeep-alive-enabled
is true.- result<list<
incoming-datagram
>,error-code
>Equivalent to the SO_KEEPALIVE socket option.
++
[method]incoming-datagram-stream.subscribe: func
Create a
+pollable
which will resolve once the stream is ready to receive again.Note: this function is here for WASI Preview2 only. +It's planned to be removed when
future
is natively supported in Preview3.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: func
Check readiness for sending. This function never blocks.
+Returns the number of datagrams permitted for the next call to
+send
, +or an error. Callingsend
with more datagrams than this function has +permitted will trap.When this function returns ok(0), the
+subscribe
pollable will +become ready when this function will report at least ok(1), or an +error.Never returns
would-block
.Params
-
- -
self
: borrow<tcp-socket
>- +
value
:bool
self
: borrow<outgoing-datagram-stream
>Return values
-
-- result<_,
+error-code
>- result<
u64
,error-code
>-
[method]tcp-socket.keep-alive-idle-time: func
Amount of time the connection has to be idle before TCP starts sending keepalive packets.
-If the provided value is 0, an
-invalid-argument
error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)
++
[method]outgoing-datagram-stream.send: func
Send messages on the socket.
+This function attempts to send all provided
+datagrams
on the socket without blocking and +returns how many messages were actually sent (or queued for sending). This function never +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
+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 precedingcheck-send
. Implementations must trap if +eithercheck-send
was not called ordatagrams
contains more items thancheck-send
permitted.Typical errors
-
-- -
invalid-argument
: (set) The provided value was 0.Params
--
-- +
self
: borrow<tcp-socket
>- +
invalid-argument
: Theremote-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 inremote-address
is set to INADDR_ANY (0.0.0.0
/::
). (EDESTADDRREQ, EADDRNOTAVAIL)- +
invalid-argument
: The port inremote-address
is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)- +
invalid-argument
: The socket is in "connected" mode andremote-address
issome
value that does not match the address passed tostream
. (EISCONN)- +
invalid-argument
: The socket is not "connected" and no value forremote-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)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: func
Params
-
- -
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: func
The time between keepalive packets.
-If the provided value is 0, an
-invalid-argument
error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.Equivalent to the TCP_KEEPINTVL socket option.
-Typical errors
--
+- +
invalid-argument
: (set) The provided value was 0.- result<
u64
,error-code
>+
[method]outgoing-datagram-stream.subscribe: func
Create a
+pollable
which will resolve once the stream is ready to send again.Note: this function is here for WASI Preview2 only. +It's planned to be removed when
future
is natively supported in Preview3.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: func
Params
--
-- -
self
: borrow<tcp-socket
>- -
value
:duration
Return values
--
-- result<_,
-error-code
>-
[method]tcp-socket.keep-alive-count: func
The maximum amount of keepalive packets TCP should send before aborting the connection.
-If the provided value is 0, an
-invalid-argument
error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.Equivalent to the TCP_KEEPCNT socket option.
-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: func
Params
--
-- -
self
: borrow<tcp-socket
>- -
value
:u32
Return values
--
-- result<_,
-error-code
>-
[method]tcp-socket.hop-limit: func
Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
-If the provided value is 0, an
-invalid-argument
error is returned.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: func
Params
--
-- -
self
: borrow<tcp-socket
>- -
value
:u8
Return values
--
-- result<_,
-error-code
>-
[method]tcp-socket.receive-buffer-size: func
The 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.
-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: func
Params
--
-- -
self
: borrow<tcp-socket
>- -
value
:u64
Return values
--
-- result<_,
-error-code
>-
[method]tcp-socket.send-buffer-size: func
Params
--
-- -
self
: borrow<tcp-socket
>Return values
--
-- result<
-u64
,error-code
>-
[method]tcp-socket.set-send-buffer-size: func
Params
--
-- -
self
: borrow<tcp-socket
>- -
value
:u64
Return values
--
-- result<_,
-error-code
>-
[method]tcp-socket.subscribe: func
Create a
-pollable
which will resolve once the socket is ready for I/O.Note: this function is here for WASI Preview2 only. -It's planned to be removed when
-future
is natively supported in Preview3.Params
--
-- -
self
: borrow<tcp-socket
>Return values
--
-- own<
-pollable
>-
[method]tcp-socket.shutdown: func
Initiate a graceful shutdown.
--
-- receive: the socket is not expecting to receive any more data from the peer. All subsequent read -operations on the
-input-stream
associated with this socket will return an End Of Stream indication. -Any data still in the receive queue at time of callingshutdown
will be discarded.- send: the socket is not expecting to send any more data to the peer. All subsequent write -operations on the
-output-stream
associated with this socket will return an error.- both: same effect as receive & send combined.
-The shutdown function does not close (drop) the socket.
-Typical errors
--
-- -
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-type
Return 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 network
output-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)
----
Functions
--
create-tcp-socket: func
Create a new TCP socket.
-Similar to
+socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP)
in POSIX.+
create-udp-socket: func
Create a new UDP socket.
+Similar to
socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP)
in POSIX.This function does not require a network capability handle. This is considered to be safe because -at time of creation, the socket is not bound to any
+at time of creation, the socket is not bound to anynetwork
yet. Up to the momentbind
/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 momentbind
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-family
is 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-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 ofrecvfrom
.Similar to `SHUT_RD` in POSIX.
-
record outgoing-datagram
A 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
+ +send
in 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-socket
A TCP socket handle.
Functions
-+
[method]udp-socket.start-bind: func
[method]tcp-socket.start-bind: func
Bind 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.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.
Typical
start
errors
- +
invalid-argument
: Thelocal-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 hasipv6-only
enabled. (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.finish
errorsParams
-
- -
self
: borrow<udp-socket
>- -
network
: borrow<network
>- +
local-address
:ip-socket-address
- +
self
: borrow<tcp-socket
>- +
network
: borrow<network
>local-address
:ip-socket-address
Return values
-
-- result<_,
+error-code
>- result<_,
error-code
>+
[method]udp-socket.finish-bind: func
[method]tcp-socket.finish-bind: func
Params
-
- +
self
: borrow<udp-socket
>self
: borrow<tcp-socket
>Return values
-
-- result<_,
+error-code
>- result<_,
error-code
>-
[method]udp-socket.stream: func
Set up inbound & outbound communication channels, optionally to a specific peer.
-This function only changes the local socket configuration and does not generate any network traffic. -On success, the
-remote-address
of the socket is updated. Thelocal-address
may be updated as well, -based on the best network path toremote-address
.When a
+remote-address
is provided, the returned streams are limited to communicating with that specific peer:+
[method]tcp-socket.start-connect: func
Connect to a remote endpoint.
+On success:
-
-- -
send
can only be used to send to this destination.- +
receive
will 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
-stream
again.The POSIX equivalent in pseudo-code is:
--if (was previously connected) { - connect(s, AF_UNSPEC) -} -if (remote_address is Some) { - connect(s, remote_address) -} -
Unlike in POSIX, the socket must already be explicitly bound.
-Typical errors
+POSIX mentions:
+++If connect() fails, the state of the socket is unspecified. Conforming applications should +close the file descriptor and create a new socket before attempting to reconnect.
+WASI prescribes the following behavior:
++
+- If
+connect
fails because an input/state validation error, the socket should remain usable.- If a connection was actually attempted but failed, the socket should become unusable for further network communication. +Besides
+drop
, any method after such a failure may return an error.Typical
start
errors+
- +
invalid-argument
: Theremote-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 hasipv6-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 inremote-address
is set to INADDR_ANY (0.0.0.0
/::
). (EDESTADDRREQ, EADDRNOTAVAIL)- -
invalid-argument
: The port inremote-address
is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)- +
invalid-state
: The socket is not bound.- +
invalid-argument
: The IP address inremote-address
is set to INADDR_ANY (0.0.0.0
/::
). (EADDRNOTAVAIL on Windows)- +
invalid-argument
: The port inremote-address
is set to 0. (EADDRNOTAVAIL on Windows)- +
invalid-argument
: The socket is already attached to a different network. Thenetwork
passed toconnect
must 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
+finish
errors+
- +
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
: Aconnect
operation 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-address
Return values
-
-- result<(own<
+incoming-datagram-stream
>, own<outgoing-datagram-stream
>),error-code
>- result<_,
error-code
>-
[method]udp-socket.local-address: func
Get the current bound address.
++
[method]tcp-socket.finish-connect: func
Params
++
+- +
self
: borrow<tcp-socket
>Return values
++
+- result<(own<
+input-stream
>, own<output-stream
>),error-code
>+
[method]tcp-socket.start-listen: func
Start listening for new connections.
+Transitions the socket into the Listener state.
+Unlike POSIX:
++
+- this function is async. This enables interactive WASI hosts to inject permission prompts.
+- the socket must already be explicitly bound.
+Typical
+start
errors+
+- +
invalid-state
: The socket is not bound to any local address. (EDESTADDRREQ)- +
invalid-state
: The socket is already in the Connection state. (EISCONN, EINVAL on BSD)- +
invalid-state
: The socket is already in the Listener state.Typical
+finish
errors+
+- +
address-in-use
: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)- +
not-in-progress
: Alisten
operation 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: func
Params
++
+- +
self
: borrow<tcp-socket
>Return values
++
+- result<_,
+error-code
>+
[method]tcp-socket.accept: func
Accept 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-size
On success, this function returns the newly accepted client socket along with +a pair of streams that can be used to read & write to the connection.
+Typical errors
++
+- +
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: func
Get 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
address
is 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: func
Get 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: func
Whether 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: func
Whether 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: func
Whether 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)this
socket 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: func
Params
++
+- +
self
: borrow<tcp-socket
>- +
value
:bool
Return values
++
+- result<_,
+error-code
>+
[method]tcp-socket.set-listen-backlog-size: func
Hints the desired listen queue size. Implementations are free to ignore this.
+If the provided value is 0, an
+invalid-argument
error is returned. +Any other value will never cause an error, but it might be silently clamped and/or rounded.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
:u64
Return values
-
-- result<
-ip-socket-address
,error-code
>-
[method]udp-socket.remote-address: func
Get 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: func
Enables 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-interval
keep-alive-count
+These properties can be configured whilekeep-alive-enabled
is false, but only come into effect whenkeep-alive-enabled
is 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: func
Whether this is a IPv4 or IPv6 socket.
-Equivalent to the SO_DOMAIN socket option.
+
[method]tcp-socket.set-keep-alive-enabled: func
Params
-
- +
self
: borrow<udp-socket
>- +
self
: borrow<tcp-socket
>value
:bool
Return values
-
-- +
ip-address-family
- result<_,
error-code
>-
[method]udp-socket.ipv6-only: func
Whether IPv4 compatibility (dual-stack) mode is disabled or not.
-Equivalent to the IPV6_V6ONLY socket option.
++
[method]tcp-socket.keep-alive-idle-time: func
Amount of time the connection has to be idle before TCP starts sending keepalive packets.
+If the provided value is 0, an
+invalid-argument
error is returned. +Any other value will never cause an error, but it might be silently clamped and/or rounded. +I.e. after setting a value, reading the same setting back may return a different value.Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)
Typical errors
-
- -
not-supported
: (get/set)this
socket is an IPv4 socket.- -
invalid-state
: (set) The socket is already bound.- +
not-supported
: (set) Host does not support dual-stack sockets. (Implementations are not required to.)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: func
Params
-
- -
self
: borrow<udp-socket
>- +
value
:bool
- +
self
: borrow<tcp-socket
>value
:duration
Return values
-
-- result<_,
+error-code
>- result<_,
error-code
>-
[method]udp-socket.unicast-hop-limit: func
Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
-If the provided value is 0, an
+invalid-argument
error is returned.+
[method]tcp-socket.keep-alive-interval: func
The time between keepalive packets.
+If the provided value is 0, an
+invalid-argument
error is returned. +Any other value will never cause an error, but it might be silently clamped and/or rounded. +I.e. after setting a value, reading the same setting back may return a different value.Equivalent to the TCP_KEEPINTVL socket option.
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: func
Params
-
- -
self
: borrow<udp-socket
>- +
value
:u8
- +
self
: borrow<tcp-socket
>value
:duration
Return values
-
-- result<_,
+error-code
>- result<_,
error-code
>-
[method]udp-socket.receive-buffer-size: func
The kernel buffer space reserved for sends/receives on this socket.
++
[method]tcp-socket.keep-alive-count: func
The maximum amount of keepalive packets TCP should send before aborting the connection.
If the provided value is 0, an
-invalid-argument
error is returned. Any other value will never cause an error, but it might be silently clamped and/or rounded. I.e. after setting a value, reading the same setting back may return a different value.Equivalent to the 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: func
Params
-
- -
self
: borrow<udp-socket
>- +
value
:u64
- +
self
: borrow<tcp-socket
>value
:u32
Return values
-
-- result<_,
-error-code
>-
[method]udp-socket.send-buffer-size: func
Params
--
-- +
self
: borrow<udp-socket
>- result<_,
error-code
>Return values
++
[method]tcp-socket.hop-limit: func
Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+If the provided value is 0, an
+invalid-argument
error is returned.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: func
Params
-
- -
self
: borrow<udp-socket
>- +
value
:u64
self
: borrow<tcp-socket
>Return values
-
-- result<_,
+error-code
>- result<
u8
,error-code
>-
[method]udp-socket.subscribe: func
Create a
-pollable
which will resolve once the socket is ready for I/O.Note: this function is here for WASI Preview2 only. -It's planned to be removed when
+future
is natively supported in Preview3.
[method]tcp-socket.set-hop-limit: func
Params
-
- +
self
: borrow<udp-socket
>- +
self
: borrow<tcp-socket
>value
:u8
Return values
-
-- own<
+pollable
>- result<_,
error-code
>-
[method]incoming-datagram-stream.receive: func
Receive messages on the socket.
-This function attempts to receive up to
-max-results
datagrams on the socket without blocking. -The returned list may contain fewer elements than requested, but never more.This function returns successfully with an empty list when either:
++
[method]tcp-socket.receive-buffer-size: func
The 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.
+Typical errors
-
-- -
max-results
is 0, or:- +
max-results
is 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: func
Params
-
- -
self
: borrow<incoming-datagram-stream
>- +
max-results
:u64
- +
self
: borrow<tcp-socket
>value
:u64
Return values
-
-- result<list<
+incoming-datagram
>,error-code
>- result<_,
error-code
>-
[method]incoming-datagram-stream.subscribe: func
Create a
-pollable
which will resolve once the stream is ready to receive again.Note: this function is here for WASI Preview2 only. -It's planned to be removed when
+future
is natively supported in Preview3.
[method]tcp-socket.send-buffer-size: func
Params
-
- +
self
: borrow<incoming-datagram-stream
>self
: borrow<tcp-socket
>Return values
-
-- own<
+pollable
>- result<
u64
,error-code
>-
[method]outgoing-datagram-stream.check-send: func
Check readiness for sending. This function never blocks.
-Returns the number of datagrams permitted for the next call to
-send
, -or an error. Callingsend
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
.
[method]tcp-socket.set-send-buffer-size: func
Params
-
- +
self
: borrow<outgoing-datagram-stream
>- +
self
: borrow<tcp-socket
>value
:u64
Return values
-
-- result<
+u64
,error-code
>- result<_,
error-code
>-
[method]outgoing-datagram-stream.send: func
Send messages on the socket.
-This function attempts to send all provided
-datagrams
on the socket without blocking and -returns how many messages were actually sent (or queued for sending). This function never -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
-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 precedingcheck-send
. Implementations must trap if -eithercheck-send
was not called ordatagrams
contains more items thancheck-send
permitted.Typical errors
++
[method]tcp-socket.subscribe: func
Create a
+pollable
which will resolve once the socket is ready for I/O.Note: this function is here for WASI Preview2 only. +It's planned to be removed when
+future
is natively supported in Preview3.Params
-
-- -
invalid-argument
: Theremote-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 inremote-address
is set to INADDR_ANY (0.0.0.0
/::
). (EDESTADDRREQ, EADDRNOTAVAIL)- -
invalid-argument
: The port inremote-address
is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)- -
invalid-argument
: The socket is in "connected" mode andremote-address
issome
value that does not match the address passed tostream
. (EISCONN)- -
invalid-argument
: The socket is not "connected" and no value forremote-address
was provided. (EDESTADDRREQ)- -
remote-unreachable
: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)- -
connection-refused
: The connection was refused. (ECONNREFUSED)- +
datagram-too-large
: The datagram is too large. (EMSGSIZE)self
: borrow<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: func
Initiate a graceful shutdown.
++
+- receive: the socket is not expecting to receive any more data from the peer. All subsequent read +operations on the
+input-stream
associated with this socket will return an End Of Stream indication. +Any data still in the receive queue at time of callingshutdown
will be discarded.- send: the socket is not expecting to send any more data to the peer. All subsequent write +operations on the
+output-stream
associated with this socket will return an error.- both: same effect as receive & send combined.
+The shutdown function does not close (drop) the socket.
+Typical errors
-
-- -
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: func
Create a
-pollable
which will resolve once the stream is ready to send again.Note: this function is here for WASI Preview2 only. -It's planned to be removed when
future
is natively supported in Preview3.Params
-
- +
self
: borrow<outgoing-datagram-stream
>- +
self
: borrow<tcp-socket
>shutdown-type
:shutdown-type
Return 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 network
future
is 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: func
Create a new UDP socket.
-Similar to
+socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP)
in POSIX.+
create-tcp-socket: func
Create a new TCP socket.
+Similar to
socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP)
in POSIX.This function does not require a network capability handle. This is considered to be safe because -at time of creation, the socket is not bound to any
+at time of creation, the socket is not bound to anynetwork
yet. Up to the momentbind
is called, -the socket is effectively an in-memory configuration object, unable to communicate with the outside world.network
yet. 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-family
is 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: func
Resolve an internet host name to a list of IP addresses.
+Unicode domain names are automatically converted to ASCII using IDNA encoding. +If the input is an IP address string, the address is parsed and returned +as-is without making any external requests.
+See the wasi-socket proposal README.md for a comparison with getaddrinfo.
+This function never blocks. It either immediately fails or immediately +returns successfully with a
+resolve-address-stream
that can be used +to (asynchronously) fetch the results.Typical errors
++
+- +
invalid-argument
:name
is 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: func
Returns the next address from the resolver.
+This function should be called multiple times. On each call, it will +return the next address in connection order preference. If all +addresses have been exhausted, this function returns
+none
.This function never returns IPv4-mapped IPv6 addresses.
+Typical errors
++
+- +
name-unresolvable
: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)- +
temporary-resolver-failure
: A temporary failure in name resolution occurred. (EAI_AGAIN)- +
permanent-resolver-failure
: A permanent failure in name resolution occurred. (EAI_FAIL)- +
would-block
: A result is not available yet. (EWOULDBLOCK, EAGAIN)Params
++
+- +
self
: borrow<resolve-address-stream
>Return values
++
+- result<option<
+ip-address
>,error-code
>+
[method]resolve-address-stream.subscribe: func
Create a
+pollable
which will resolve once the stream is ready for I/O.Note: this function is here for WASI Preview2 only. +It's planned to be removed when
+future
is natively supported in Preview3.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: func
Get 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: func
Get the POSIX-style arguments to the program.
-Return values
- --
initial-cwd: func
Return 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: func
Exit 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: func
Return values
--
-- own<
-input-stream
>Import interface wasi:cli/stdout@0.2.0-rc-2023-11-10
-
-Types
-- -
type output-stream
----- -
Functions
--
get-stdout: func
Return values
--
-- own<
-output-stream
>Import interface wasi:cli/stderr@0.2.0-rc-2023-11-10
-
-Types
-- -
type output-stream
----- -
Functions
--
get-stderr: func
Return values
--
-- own<
-output-stream
>Import interface wasi:cli/terminal-input@0.2.0-rc-2023-11-10
-
-Types
--
resource terminal-input
Import interface wasi:cli/terminal-output@0.2.0-rc-2023-11-10
-
-Types
--
resource terminal-output
Import interface wasi:cli/terminal-stdin@0.2.0-rc-2023-11-10
-An interface providing an optional
-terminal-input
for stdin as a -link-time authority.
-Types
-- -
type terminal-input
----- -
Functions
--
get-terminal-stdin: func
If stdin is connected to a terminal, return a
-terminal-input
handle -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-output
for stdout as a -link-time authority.
-Types
-- -
type terminal-output
----- -
Functions
--
get-terminal-stdout: func
If stdout is connected to a terminal, return a
-terminal-output
handle -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-output
for stderr as a -link-time authority.
-Types
-- -
type terminal-output
----- -
Functions
--
get-terminal-stderr: func
If stderr is connected to a terminal, return a
-terminal-output
handle -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
>>