From 489922c754d7b242252f10fdef1d752a60dd9cb1 Mon Sep 17 00:00:00 2001 From: "Jiaxiao Zhou (Mossaka)" Date: Sat, 21 Oct 2023 00:12:47 -0700 Subject: [PATCH 1/2] simplify command.wit with `include` syntax this PR is a follow up on #23 and simplifies the command world with incldue syntax to hide all the interfaces from deps. Signed-off-by: Jiaxiao Zhou (Mossaka) --- wit/reactor.wit | 21 +++++---------------- 1 file changed, 5 insertions(+), 16 deletions(-) diff --git a/wit/reactor.wit b/wit/reactor.wit index eafa2fd..4cd4710 100644 --- a/wit/reactor.wit +++ b/wit/reactor.wit @@ -1,22 +1,11 @@ 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; + 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; From 304d5efb39f9b8c28df9929e6ed72dc56b4f4537 Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Wed, 15 Nov 2023 13:54:08 -0800 Subject: [PATCH 2/2] Auto-generate command.md and reactor.md. --- command.md | 2082 ++++++++++++++++++++++++++-------------------------- reactor.md | 2082 ++++++++++++++++++++++++++-------------------------- 2 files changed, 2118 insertions(+), 2046 deletions(-) diff --git a/command.md b/command.md index dda65a8..be37528 100644 --- a/command.md +++ b/command.md @@ -2,33 +2,33 @@ -

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
+

get-arguments: func

+

Get the POSIX-style arguments to the program.

+
Return values
+
    +
  • list<string>
    • +
+

initial-cwd: func

+

Return a path that programs should use as their initial current working +directory, interpreting . as shorthand for this.

+
Return values
+
    +
  • option<string>
+

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, errors returned in streams derived +from filesystem types to be described using the filesystem's own +error-code type, using the function +wasi:filesystem/types/filesystem-error-code, which takes a parameter +borrow<error> and returns +option<wasi:filesystem/types/error-code>.

+

The set of functions which can "downcast" an 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

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 @@ -84,7 +114,7 @@ at once.

Types

resource pollable

-
+

pollable epresents 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.

@@ -128,88 +158,6 @@ being reaedy for I/O.

  • list<u32>
-

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

-

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
- -

resolution: func

-

Query the resolution of the clock. Returns the duration of time -corresponding to a clock tick.

-
Return values
- -

subscribe-instant: func

-

Create a pollable which will resolve once the specified instant -occured.

-
Params
- -
Return values
- -

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
- -

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
-
    -
  • string
    • -

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.

@@ -240,8 +188,21 @@ future operations.

resource input-stream

+

An input bytestream.

+

input-streams are non-blocking to the extent practical on underlying +platforms. I/O operations always return promptly; if fewer bytes are +promptly available than requested, they return the number of bytes promptly +available, which could even be zero. To wait for data to be available, +use the subscribe function to obtain a pollable which can be polled +for using wasi:io/poll.

resource output-stream

-
+

An output bytestream.

+

output-streams are non-blocking to the extent practical on +underlying platforms. Except where specified otherwise, I/O operations also +always return promptly, after the number of bytes that can be written +promptly, which could even be zero. To wait for the stream to be ready to +accept data, the subscribe function to obtain a pollable which can be +polled for using wasi:io/poll.

Functions

[method]input-stream.read: func

Perform a non-blocking read from the stream.

@@ -513,48 +474,250 @@ is ready for reading, before performing the splice.

-

Import interface wasi:filesystem/types@0.2.0-rc-2023-11-10

-

WASI filesystem is a filesystem API primarily intended to let users run WASI -programs that access their files on their existing filesystems, without -significant overhead.

-

It is intended to be roughly portable between Unix-family platforms and -Windows, though it does not hide many of the major differences.

-

Paths are passed as interface-type strings, meaning they must consist of -a sequence of Unicode Scalar Values (USVs). Some filesystems may contain -paths which are not accessible by this API.

-

The directory separator in WASI is always the forward-slash (/).

-

All paths in WASI are relative paths, and are interpreted relative to a -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.

+

Import interface wasi:cli/stdin@0.2.0-rc-2023-11-10

Types

type input-stream

input-stream

-#### `type output-stream` -[`output-stream`](#output_stream) -

-#### `type error` -[`error`](#error) +---- +

Functions

+

get-stdin: func

+
Return values
+ +

Import interface wasi:cli/stdout@0.2.0-rc-2023-11-10

+
+

Types

+

type output-stream

+

output-stream

-#### `type datetime` -[`datetime`](#datetime) +---- +

Functions

+

get-stdout: func

+
Return values
+ +

Import interface wasi:cli/stderr@0.2.0-rc-2023-11-10

+
+

Types

+

type output-stream

+

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
+

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

+

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
+ +

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

+

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
+ +

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

+

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
+ +

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

+

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
+ +

resolution: func

+

Query the resolution of the clock. Returns the duration of time +corresponding to a clock tick.

+
Return values
+ +

subscribe-instant: func

+

Create a pollable which will resolve once the specified instant +occured.

+
Params
+ +
Return values
+ +

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
+ +

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
+ +
+

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
+ +

resolution: func

+

Query the resolution of the clock.

+

The nanoseconds field of the output is always less than 1000000000.

+
Return values
+ +

Import interface wasi:filesystem/types@0.2.0-rc-2023-11-10

+

WASI filesystem is a filesystem API primarily intended to let users run WASI +programs that access their files on their existing filesystems, without +significant overhead.

+

It is intended to be roughly portable between Unix-family platforms and +Windows, though it does not hide many of the major differences.

+

Paths are passed as interface-type strings, meaning they must consist of +a sequence of Unicode Scalar Values (USVs). Some filesystems may contain +paths which are not accessible by this API.

+

The directory separator in WASI is always the forward-slash (/).

+

All paths in WASI are relative paths, and are interpreted relative to a +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.

+
+

Types

+

type input-stream

+

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
+
    +
  • +

    unknown

    The type of the descriptor or file is unknown or is different from any of the other types specified.

    • @@ -943,8 +1106,11 @@ not reuse it thereafter.

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.

@@ -1408,6 +1574,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. @@ -1589,7 +1758,7 @@ combined with a couple of errors that are always possible:

-

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

type pollable

@@ -1601,133 +1770,62 @@ combined with a couple of errors that are always possible:

#### `type error-code` [`error-code`](#error_code)

-#### `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
-
Params
+

record outgoing-datagram

+

A datagram to be sent out.

+
Record Fields
-
Return values
- -

[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
- -
Return values
- -

[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
- -
Return values
- -

Import interface wasi:sockets/tcp@0.2.0-rc-2023-11-10

-
-

Types

-

type input-stream

-

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
-
    -
  • -

    receive

    -

    Similar to `SHUT_RD` in POSIX. -

  • -

    send

    -

    Similar to `SHUT_WR` in POSIX. +

    data: list<u8>

    +

    The payload.

  • -

    both

    -

    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 to sendto.

-

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: The local-address has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
    • -
  • invalid-argument: local-address is not a unicast address. (EINVAL)
    • -
  • invalid-argument: local-address is an IPv4-mapped IPv6 address, but the socket has ipv6-only enabled. (EINVAL)
  • invalid-state: The socket is already bound. (EINVAL)

Typical finish errors

@@ -1747,63 +1845,55 @@ implicitly bind the socket.

Params
Return values
-

[method]tcp-socket.finish-bind: func

+

[method]udp-socket.finish-bind: func

Params
Return values
-

[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. 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:

    -
  • 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 provided remote-address.
-

Typical start errors

+

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

  • invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)
    • -
  • invalid-argument: remote-address is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)
    • -
  • invalid-argument: remote-address is an IPv4-mapped IPv6 address, but the socket has ipv6-only enabled. (EINVAL, EADDRNOTAVAIL on Illumos)
  • invalid-argument: remote-address is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)
    • -
  • invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EADDRNOTAVAIL on Windows)
    • -
  • invalid-argument: The port in remote-address is set to 0. (EADDRNOTAVAIL on Windows)
    • -
  • invalid-argument: The socket is already attached to a different network. The network passed to connect must be identical to the one passed to bind.
    • -
  • invalid-state: The socket is already in the Connection state. (EISCONN)
    • -
  • invalid-state: The socket is already in the Listener state. (EOPNOTSUPP, EINVAL on Windows)
    • -
-

Typical finish errors

-
    -
  • timeout: Connection timed out. (ETIMEDOUT)
    • -
  • connection-refused: The connection was forcefully rejected. (ECONNREFUSED)
    • -
  • connection-reset: The connection was reset. (ECONNRESET)
    • -
  • 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)

References

    @@ -1814,453 +1904,303 @@ Besides drop, any method after such a failure may return an error.<
Params
Return values
-

[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 return invalid-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

-

[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 errors

+
Return 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: 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)

References

Params
Return values
-

[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
Return values
-

[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
+

[method]udp-socket.set-ipv6-only: func

Params
Return values
-

[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.

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
+
Return values
+ +

[method]udp-socket.set-unicast-hop-limit: func

Params
Return values
-

[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

-
Params
Return values
-

[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
Return values
-

[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
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
Return values
-

[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
Return values
+

[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.

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

-
Return values
+
Params
-

[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 while keep-alive-enabled is false, but only come into effect when keep-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
Return values
-

[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.

Params
Return values
-

[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.

Typical errors

    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
-
    -
  • 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)
-
Return values
+

References

-

[method]tcp-socket.set-keep-alive-idle-time: func

Params
Return values
-

[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
Return values
-

[method]tcp-socket.set-keep-alive-interval: func

-
Params
- -
Return values
- -

[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
- -
Return values
- -

[method]tcp-socket.set-keep-alive-count: func

-
Params
- -
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

-
    -
  • invalid-argument: (set) The TTL value must be 1 or higher.
    • -
  • invalid-state: (set) The socket is already in the Connection state.
    • -
  • invalid-state: (set) The socket is already in the Listener state.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-hop-limit: func

-
Params
- -
Return values
- -

[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
- -
Return values
- -

[method]tcp-socket.set-receive-buffer-size: func

-
Params
- -
Return values
- -

[method]tcp-socket.send-buffer-size: func

-
Params
- -
Return values
- -

[method]tcp-socket.set-send-buffer-size: func

-
Params
- -
Return values
- -

[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
- -
Return values
- -

[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 calling shutdown will be discarded.
    • -
  • send: the socket is not expecting to send any more data to the peer. All subsequent write -operations on the output-stream associated with this socket will return an error.
    • -
  • both: same effect as receive & send combined.
    • -
-

The shutdown function does not close (drop) the socket.

-

Typical errors

-
    -
  • invalid-state: The socket is not in the Connection state. (ENOTCONN)
    • -
-

References

- -
Params
- -
Return values
- -

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

type network

@@ -2272,24 +2212,24 @@ operations on the 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 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.

+at time of creation, the socket is not bound to any network yet. Up to the moment bind is called, +the socket is effectively an in-memory configuration object, unable to communicate with the outside world.

All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.

Typical errors

  • not-supported: The specified address-family is not supported. (EAFNOSUPPORT)
  • new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
-

References

+

References:

Params
Return values
-

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

-

pollable

+

type input-stream

+

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.

-
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 of recvfrom.

    +

    receive

    +

    Similar to `SHUT_RD` in POSIX.

    • -
-

record outgoing-datagram

-

A datagram to be sent out.

-
Record Fields
-
  • -

    data: list<u8>

    -

    The payload. +

    send

    +

    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 to sendto.

    +

    both

    +

    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 (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.

+If the TCP/UDP port is zero, the socket will be bound to a random free port.

+

When a socket is not explicitly bound, the first invocation to a listen or connect operation will +implicitly bind the socket.

Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.

Typical start errors

  • invalid-argument: The local-address has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
    • +
  • invalid-argument: local-address is not a unicast address. (EINVAL)
    • +
  • invalid-argument: local-address is an IPv4-mapped IPv6 address, but the socket has ipv6-only enabled. (EINVAL)
  • invalid-state: The socket is already bound. (EINVAL)

Typical finish errors

@@ -2390,55 +2322,63 @@ If the port is zero, the socket will be bound to a random free port.

Params
Return values
-

[method]udp-socket.finish-bind: func

+

[method]tcp-socket.finish-bind: func

Params
Return values
-

[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.
    • +
  • 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: 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)
    • +
+

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: A connect operation is not in progress.
    • +
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)

References

    @@ -2449,15 +2389,107 @@ if (remote_address is Some) {
Params
Return values
-

[method]udp-socket.local-address: func

-

Get the current bound address.

+

[method]tcp-socket.finish-connect: func

+
Params
+ +
Return values
+ +

[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: A listen operation is not in progress.
    • +
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
    • +
+

References

+ +
Params
+ +
Return values
+ +

[method]tcp-socket.finish-listen: func

+
Params
+ +
Return values
+ +

[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

+ +
Params
+ +
Return values
+ +

[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

+
Params
+ +
Return values
+ +

[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

+ +
Params
+ +
Return values
+ +

[method]tcp-socket.is-listening: func

+

Whether the socket is listening for new connections.

+

Equivalent to the SO_ACCEPTCONN socket option.

+
Params
+ +
Return values
+
    +
  • bool
    • +
+

[method]tcp-socket.address-family: func

+

Whether this is a IPv4 or IPv6 socket.

+

Equivalent to the SO_DOMAIN socket option.

+
Params
+ +
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
+ +
Return values
+ +

[method]tcp-socket.set-ipv6-only: func

+
Params
+ +
Return values
+ +

[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
Return values
-

[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:

+

Equivalent to the SO_KEEPALIVE socket option.

Params
Return values
-

[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
Return values
-

[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
Return values
-

[method]udp-socket.set-ipv6-only: func

+

[method]tcp-socket.set-keep-alive-idle-time: func

Params
Return values
-

[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
Return values
-

[method]udp-socket.set-unicast-hop-limit: func

+

[method]tcp-socket.set-keep-alive-interval: func

Params
Return values
-

[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
Return values
-

[method]udp-socket.set-receive-buffer-size: func

+

[method]tcp-socket.set-keep-alive-count: func

Params
Return values
-

[method]udp-socket.send-buffer-size: func

-
Params
- -
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
Return values
-

[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
Return values
-

[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 returns error(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
+

[method]tcp-socket.set-receive-buffer-size: func

Params
Return values
-

[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
Return values
-

[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.

+

[method]tcp-socket.set-send-buffer-size: func

Params
Return values
-

[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.

-

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: The remote-address has the wrong address family. (EAFNOSUPPORT)
    • -
  • invalid-argument: remote-address is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)
    • -
  • invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-argument: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-argument: The socket is in "connected" mode and remote-address is some value that does not match the address passed to stream. (EISCONN)
    • -
  • invalid-argument: The socket is not "connected" and no value for remote-address was provided. (EDESTADDRREQ)
    • -
  • remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • -
  • connection-refused: The connection was refused. (ECONNREFUSED)
    • -
  • datagram-too-large: The datagram is too large. (EMSGSIZE)
    • +
  • self: borrow<tcp-socket>
-

References

+
Return values
-
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 calling shutdown will be discarded.
    • +
  • send: the socket is not expecting to send any more data to the peer. All subsequent write +operations on the output-stream associated with this socket will return an error.
    • +
  • both: same effect as receive & send combined.
    • +
+

The shutdown function does not close (drop) the socket.

+

Typical errors

-
Return values
+

References

-

[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
Return values
-

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

type network

@@ -2757,24 +2847,24 @@ It's planned to be removed when 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 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.

+at time of creation, the socket is not bound to any network yet. Up to the moment bind/listen/connect +is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world.

All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.

Typical errors

  • not-supported: The specified address-family is not supported. (EAFNOSUPPORT)
  • new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
-

References:

+

References

Params
Return values
+

Import interface wasi:sockets/ip-name-lookup@0.2.0-rc-2023-11-10

+
+

Types

+

type pollable

+

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:

+ +
Params
+ +
Return values
+ +

[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
+ +
Return values
+ +

[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
+ +
Return values
+

Import interface wasi:random/random@0.2.0-rc-2023-11-10

WASI Random is a random data API.

@@ -2875,140 +3045,6 @@ protection.

  • (u64, u64)
-

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
-
    -
  • list<(string, string)>
    • -
-

get-arguments: func

-

Get the POSIX-style arguments to the program.

-
Return values
-
    -
  • list<string>
    • -
-

initial-cwd: func

-

Return a path that programs should use as their initial current working -directory, interpreting . as shorthand for this.

-
Return values
-
    -
  • option<string>
    • -
-

Import interface wasi:cli/exit@0.2.0-rc-2023-11-10

-
-

Functions

-

exit: func

-

Exit the current instance and any linked instances.

-
Params
- -

Import interface wasi:cli/stdin@0.2.0-rc-2023-11-10

-
-

Types

-

type input-stream

-

input-stream

-

----- -

Functions

-

get-stdin: func

-
Return values
- -

Import interface wasi:cli/stdout@0.2.0-rc-2023-11-10

-
-

Types

-

type output-stream

-

output-stream

-

----- -

Functions

-

get-stdout: func

-
Return values
- -

Import interface wasi:cli/stderr@0.2.0-rc-2023-11-10

-
-

Types

-

type output-stream

-

output-stream

-

----- -

Functions

-

get-stderr: func

-
Return values
- -

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

-

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
- -

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

-

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
- -

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

-

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
-

Export interface wasi:cli/run@0.2.0-rc-2023-11-10

Functions

diff --git a/reactor.md b/reactor.md index 1115e35..f3bd260 100644 --- a/reactor.md +++ b/reactor.md @@ -2,76 +2,106 @@ -

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
+

get-arguments: func

+

Get the POSIX-style arguments to the program.

+
Return values
+
    +
  • list<string>
    • +
+

initial-cwd: func

+

Return a path that programs should use as their initial current working +directory, interpreting . as shorthand for this.

+
Return values
+
    +
  • option<string>
+

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, errors returned in streams derived +from filesystem types to be described using the filesystem's own +error-code type, using the function +wasi:filesystem/types/filesystem-error-code, which takes a parameter +borrow<error> and returns +option<wasi:filesystem/types/error-code>.

+

The set of functions which can "downcast" an 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

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 epresents 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.

  • list<u32>
-

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

-

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
- -

resolution: func

-

Query the resolution of the clock. Returns the duration of time -corresponding to a clock tick.

-
Return values
- -

subscribe-instant: func

-

Create a pollable which will resolve once the specified instant -occured.

-
Params
- -
Return values
- -

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
- -

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
-
    -
  • string
    • -

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-streams are non-blocking to the extent practical on underlying +platforms. I/O operations always return promptly; if fewer bytes are +promptly available than requested, they return the number of bytes promptly +available, which could even be zero. To wait for data to be available, +use the subscribe function to obtain a pollable which can be polled +for using wasi:io/poll.

resource output-stream

-
+

An output bytestream.

+

output-streams are non-blocking to the extent practical on +underlying platforms. Except where specified otherwise, I/O operations also +always return promptly, after the number of bytes that can be written +promptly, which could even be zero. To wait for the stream to be ready to +accept data, the subscribe function to obtain a pollable which can be +polled for using wasi:io/poll.

Functions

[method]input-stream.read: func

Perform a non-blocking read from the stream.

@@ -508,48 +469,250 @@ is ready for reading, before performing the splice.

-

Import interface wasi:filesystem/types@0.2.0-rc-2023-11-10

-

WASI filesystem is a filesystem API primarily intended to let users run WASI -programs that access their files on their existing filesystems, without -significant overhead.

-

It is intended to be roughly portable between Unix-family platforms and -Windows, though it does not hide many of the major differences.

-

Paths are passed as interface-type strings, meaning they must consist of -a sequence of Unicode Scalar Values (USVs). Some filesystems may contain -paths which are not accessible by this API.

-

The directory separator in WASI is always the forward-slash (/).

-

All paths in WASI are relative paths, and are interpreted relative to a -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.

+

Import interface wasi:cli/stdin@0.2.0-rc-2023-11-10

Types

type input-stream

input-stream

-#### `type output-stream` -[`output-stream`](#output_stream) -

-#### `type error` -[`error`](#error) +---- +

Functions

+

get-stdin: func

+
Return values
+ +

Import interface wasi:cli/stdout@0.2.0-rc-2023-11-10

+
+

Types

+

type output-stream

+

output-stream

-#### `type datetime` -[`datetime`](#datetime) +---- +

Functions

+

get-stdout: func

+
Return values
+ +

Import interface wasi:cli/stderr@0.2.0-rc-2023-11-10

+
+

Types

+

type output-stream

+

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
+

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

+

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
+ +

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

+

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
+ +

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

+

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
+ +

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

+

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
+ +

resolution: func

+

Query the resolution of the clock. Returns the duration of time +corresponding to a clock tick.

+
Return values
+ +

subscribe-instant: func

+

Create a pollable which will resolve once the specified instant +occured.

+
Params
+ +
Return values
+ +

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
+ +

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
+ +
+

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
+ +

resolution: func

+

Query the resolution of the clock.

+

The nanoseconds field of the output is always less than 1000000000.

+
Return values
+ +

Import interface wasi:filesystem/types@0.2.0-rc-2023-11-10

+

WASI filesystem is a filesystem API primarily intended to let users run WASI +programs that access their files on their existing filesystems, without +significant overhead.

+

It is intended to be roughly portable between Unix-family platforms and +Windows, though it does not hide many of the major differences.

+

Paths are passed as interface-type strings, meaning they must consist of +a sequence of Unicode Scalar Values (USVs). Some filesystems may contain +paths which are not accessible by this API.

+

The directory separator in WASI is always the forward-slash (/).

+

All paths in WASI are relative paths, and are interpreted relative to a +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.

+
+

Types

+

type input-stream

+

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
+
    +
  • +

    unknown

    The type of the descriptor or file is unknown or is different from any of the other types specified.

    • @@ -938,8 +1101,11 @@ not reuse it thereafter.

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:

-

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

type pollable

@@ -1596,133 +1765,62 @@ combined with a couple of errors that are always possible:

#### `type error-code` [`error-code`](#error_code)

-#### `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
-
Params
+

record outgoing-datagram

+

A datagram to be sent out.

+
Record Fields
-
Return values
- -

[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
- -
Return values
- -

[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
- -
Return values
- -

Import interface wasi:sockets/tcp@0.2.0-rc-2023-11-10

-
-

Types

-

type input-stream

-

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
-
    -
  • -

    receive

    -

    Similar to `SHUT_RD` in POSIX. -

  • -

    send

    -

    Similar to `SHUT_WR` in POSIX. +

    data: list<u8>

    +

    The payload.

  • -

    both

    -

    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 to sendto.

-

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: The local-address has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
    • -
  • invalid-argument: local-address is not a unicast address. (EINVAL)
    • -
  • invalid-argument: local-address is an IPv4-mapped IPv6 address, but the socket has ipv6-only enabled. (EINVAL)
  • invalid-state: The socket is already bound. (EINVAL)

Typical finish errors

@@ -1742,63 +1840,55 @@ implicitly bind the socket.

Params
Return values
-

[method]tcp-socket.finish-bind: func

+

[method]udp-socket.finish-bind: func

Params
Return values
-

[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. 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:

    -
  • 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 provided remote-address.
-

Typical start errors

+

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

  • invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)
    • -
  • invalid-argument: remote-address is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)
    • -
  • invalid-argument: remote-address is an IPv4-mapped IPv6 address, but the socket has ipv6-only enabled. (EINVAL, EADDRNOTAVAIL on Illumos)
  • invalid-argument: remote-address is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)
    • -
  • invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EADDRNOTAVAIL on Windows)
    • -
  • invalid-argument: The port in remote-address is set to 0. (EADDRNOTAVAIL on Windows)
    • -
  • invalid-argument: The socket is already attached to a different network. The network passed to connect must be identical to the one passed to bind.
    • -
  • invalid-state: The socket is already in the Connection state. (EISCONN)
    • -
  • invalid-state: The socket is already in the Listener state. (EOPNOTSUPP, EINVAL on Windows)
    • -
-

Typical finish errors

-
    -
  • timeout: Connection timed out. (ETIMEDOUT)
    • -
  • connection-refused: The connection was forcefully rejected. (ECONNREFUSED)
    • -
  • connection-reset: The connection was reset. (ECONNRESET)
    • -
  • 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)

References

    @@ -1809,453 +1899,303 @@ Besides drop, any method after such a failure may return an error.<
Params
Return values
-

[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 return invalid-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

-

[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 errors

+
Return 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: 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)

References

Params
Return values
-

[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
Return values
-

[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
+

[method]udp-socket.set-ipv6-only: func

Params
Return values
-

[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.

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
+
Return values
+ +

[method]udp-socket.set-unicast-hop-limit: func

Params
Return values
-

[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

-
Params
Return values
-

[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
Return values
-

[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
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
Return values
-

[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
Return values
+

[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.

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

-
Return values
+
Params
-

[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 while keep-alive-enabled is false, but only come into effect when keep-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
Return values
-

[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.

Params
Return values
-

[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.

Typical errors

    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
-
    -
  • 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)
-
Return values
+

References

-

[method]tcp-socket.set-keep-alive-idle-time: func

Params
Return values
-

[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
Return values
-

[method]tcp-socket.set-keep-alive-interval: func

-
Params
- -
Return values
- -

[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
- -
Return values
- -

[method]tcp-socket.set-keep-alive-count: func

-
Params
- -
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

-
    -
  • invalid-argument: (set) The TTL value must be 1 or higher.
    • -
  • invalid-state: (set) The socket is already in the Connection state.
    • -
  • invalid-state: (set) The socket is already in the Listener state.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-hop-limit: func

-
Params
- -
Return values
- -

[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
- -
Return values
- -

[method]tcp-socket.set-receive-buffer-size: func

-
Params
- -
Return values
- -

[method]tcp-socket.send-buffer-size: func

-
Params
- -
Return values
- -

[method]tcp-socket.set-send-buffer-size: func

-
Params
- -
Return values
- -

[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
- -
Return values
- -

[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 calling shutdown will be discarded.
    • -
  • send: the socket is not expecting to send any more data to the peer. All subsequent write -operations on the output-stream associated with this socket will return an error.
    • -
  • both: same effect as receive & send combined.
    • -
-

The shutdown function does not close (drop) the socket.

-

Typical errors

-
    -
  • invalid-state: The socket is not in the Connection state. (ENOTCONN)
    • -
-

References

- -
Params
- -
Return values
- -

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

type network

@@ -2267,24 +2207,24 @@ operations on the 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 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.

+at time of creation, the socket is not bound to any network yet. Up to the moment bind is called, +the socket is effectively an in-memory configuration object, unable to communicate with the outside world.

All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.

Typical errors

  • not-supported: The specified address-family is not supported. (EAFNOSUPPORT)
  • new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
-

References

+

References:

Params
Return values
-

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

-

pollable

+

type input-stream

+

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 of recvfrom.

    +

    receive

    +

    Similar to `SHUT_RD` in POSIX.

    • -
-

record outgoing-datagram

-

A datagram to be sent out.

-
Record Fields
-
  • -

    data: list<u8>

    -

    The payload. +

    send

    +

    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 to sendto.

    +

    both

    +

    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 (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.

+If the TCP/UDP port is zero, the socket will be bound to a random free port.

+

When a socket is not explicitly bound, the first invocation to a listen or connect operation will +implicitly bind the socket.

Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.

Typical start errors

  • invalid-argument: The local-address has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
    • +
  • invalid-argument: local-address is not a unicast address. (EINVAL)
    • +
  • invalid-argument: local-address is an IPv4-mapped IPv6 address, but the socket has ipv6-only enabled. (EINVAL)
  • invalid-state: The socket is already bound. (EINVAL)

Typical finish errors

@@ -2385,55 +2317,63 @@ If the port is zero, the socket will be bound to a random free port.

Params
Return values
-

[method]udp-socket.finish-bind: func

+

[method]tcp-socket.finish-bind: func

Params
Return values
-

[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.
    • +
  • 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: 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)
    • +
+

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: A connect 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
Return values
-

[method]udp-socket.local-address: func

-

Get the current bound address.

+

[method]tcp-socket.finish-connect: func

+
Params
+ +
Return values
+ +

[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: A listen operation is not in progress.
    • +
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
    • +
+

References

+ +
Params
+ +
Return values
+ +

[method]tcp-socket.finish-listen: func

+
Params
+ +
Return values
+ +

[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

+ +
Params
+ +
Return values
+ +

[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

+
Params
+ +
Return values
+ +

[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

+ +
Params
+ +
Return values
+ +

[method]tcp-socket.is-listening: func

+

Whether the socket is listening for new connections.

+

Equivalent to the SO_ACCEPTCONN socket option.

+
Params
+ +
Return values
+
    +
  • bool
    • +
+

[method]tcp-socket.address-family: func

+

Whether this is a IPv4 or IPv6 socket.

+

Equivalent to the SO_DOMAIN socket option.

+
Params
+ +
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
+ +
Return values
+ +

[method]tcp-socket.set-ipv6-only: func

+
Params
+ +
Return values
+ +

[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
Return values
-

[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:

+

Equivalent to the SO_KEEPALIVE socket option.

Params
Return values
-

[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
Return values
-

[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
Return values
-

[method]udp-socket.set-ipv6-only: func

+

[method]tcp-socket.set-keep-alive-idle-time: func

Params
Return values
-

[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
Return values
-

[method]udp-socket.set-unicast-hop-limit: func

+

[method]tcp-socket.set-keep-alive-interval: func

Params
Return values
-

[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
Return values
-

[method]udp-socket.set-receive-buffer-size: func

+

[method]tcp-socket.set-keep-alive-count: func

Params
Return values
-

[method]udp-socket.send-buffer-size: func

-
Params
- -
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
Return values
-

[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
Return values
-

[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 returns error(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
+

[method]tcp-socket.set-receive-buffer-size: func

Params
Return values
-

[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
Return values
-

[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.

+

[method]tcp-socket.set-send-buffer-size: func

Params
Return values
-

[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.

-

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: The remote-address has the wrong address family. (EAFNOSUPPORT)
    • -
  • invalid-argument: remote-address is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)
    • -
  • invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-argument: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-argument: The socket is in "connected" mode and remote-address is some value that does not match the address passed to stream. (EISCONN)
    • -
  • invalid-argument: The socket is not "connected" and no value for remote-address was provided. (EDESTADDRREQ)
    • -
  • remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • -
  • connection-refused: The connection was refused. (ECONNREFUSED)
    • -
  • datagram-too-large: The datagram is too large. (EMSGSIZE)
    • +
  • self: borrow<tcp-socket>
-

References

+
Return values
-
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 calling shutdown will be discarded.
    • +
  • send: the socket is not expecting to send any more data to the peer. All subsequent write +operations on the output-stream associated with this socket will return an error.
    • +
  • both: same effect as receive & send combined.
    • +
+

The shutdown function does not close (drop) the socket.

+

Typical errors

-
Return values
+

References

-

[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
Return values
-

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

type network

@@ -2752,24 +2842,24 @@ It's planned to be removed when 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 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.

+at time of creation, the socket is not bound to any network yet. Up to the moment bind/listen/connect +is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world.

All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.

Typical errors

  • not-supported: The specified address-family is not supported. (EAFNOSUPPORT)
  • new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
-

References:

+

References

Params
Return values
+

Import interface wasi:sockets/ip-name-lookup@0.2.0-rc-2023-11-10

+
+

Types

+

type pollable

+

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:

+ +
Params
+ +
Return values
+ +

[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
+ +
Return values
+ +

[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
+ +
Return values
+

Import interface wasi:random/random@0.2.0-rc-2023-11-10

WASI Random is a random data API.

@@ -2870,137 +3040,3 @@ protection.

  • (u64, u64)
-

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
-
    -
  • list<(string, string)>
    • -
-

get-arguments: func

-

Get the POSIX-style arguments to the program.

-
Return values
-
    -
  • list<string>
    • -
-

initial-cwd: func

-

Return a path that programs should use as their initial current working -directory, interpreting . as shorthand for this.

-
Return values
-
    -
  • option<string>
    • -
-

Import interface wasi:cli/exit@0.2.0-rc-2023-11-10

-
-

Functions

-

exit: func

-

Exit the current instance and any linked instances.

-
Params
- -

Import interface wasi:cli/stdin@0.2.0-rc-2023-11-10

-
-

Types

-

type input-stream

-

input-stream

-

----- -

Functions

-

get-stdin: func

-
Return values
- -

Import interface wasi:cli/stdout@0.2.0-rc-2023-11-10

-
-

Types

-

type output-stream

-

output-stream

-

----- -

Functions

-

get-stdout: func

-
Return values
- -

Import interface wasi:cli/stderr@0.2.0-rc-2023-11-10

-
-

Types

-

type output-stream

-

output-stream

-

----- -

Functions

-

get-stderr: func

-
Return values
- -

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

-

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
- -

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

-

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
- -

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

-

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
-