F bind

bind: func(local-address: ip-socket-address) -> result<_, error-code>;

Bind the socket to 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.

Bind can be attempted multiple times on the same socket, even with different arguments on each iteration. But never concurrently and only as long as the previous bind failed. Once a bind succeeds, the binding can't be changed anymore.

Typical 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. (EINVAL)
invalid-state: The socket is already bound. (EINVAL)
address-in-use: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
address-in-use: Address is already in use. (EADDRINUSE)
address-not-bindable: local-address is not an address that can be bound to. (EADDRNOTAVAIL)

Implementors note

The bind operation shouldn't be affected by the TIME_WAIT state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR socket option should be set implicitly on all platforms, except on Windows where this is the default behavior and SO_REUSEADDR performs something different.

References

F connect

connect: async func(remote-address: ip-socket-address) -> result<_, error-code>;

Connect to a remote endpoint.

On success, the socket is transitioned into the connected state and 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. If the socket was not already explicitly bound, this function will implicitly bind the socket to a random free port.

After a failed connection attempt, the socket will be in the closed state and the only valid action left is to drop the socket. A single socket can not be used to connect more than once.

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. (EINVAL, EADDRNOTAVAIL on Illumos)
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-state: The socket is already in the connecting state. (EALREADY)
invalid-state: The socket is already in the connected state. (EISCONN)
invalid-state: The socket is already in the listening state. (EOPNOTSUPP, EINVAL on Windows)
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)

References

F listen

listen: func() -> result<stream<tcp-socket>, error-code>;

Start listening and return a stream of new inbound connections.

Transitions the socket into the listening state. This can be called at most once per socket.

If the socket is not already explicitly bound, this function will implicitly bind the socket to a random free port.

Normally, the returned sockets are bound, in the connected state and immediately ready for I/O. Though, depending on exact timing and circumstances, a newly accepted connection may already be closed by the time the server attempts to perform its first I/O on it. This is true regardless of whether the WASI implementation uses "synthesized" sockets or not (see Implementors Notes below).

The following properties are inherited from the listener socket:

address-family
keep-alive-enabled
keep-alive-idle-time
keep-alive-interval
keep-alive-count
hop-limit
receive-buffer-size
send-buffer-size

Typical errors

invalid-state: The socket is already in the connected state. (EISCONN, EINVAL on BSD)
invalid-state: The socket is already in the listening state.
address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)

Implementors note

This method returns a single perpetual stream that should only close on fatal errors (if any). Yet, the POSIX' accept function may also return transient errors (e.g. ECONNABORTED). The exact details differ per operation system. For example, the Linux manual mentions:

Linux accept() passes already-pending network errors on the new socket as an error code from accept(). This behavior differs from other BSD socket implementations. For reliable operation the application should detect the network errors defined for the protocol after accept() and treat them like EAGAIN by retrying. In the case of TCP/IP, these are ENETDOWN, EPROTO, ENOPROTOOPT, EHOSTDOWN, ENONET, EHOSTUNREACH, EOPNOTSUPP, and ENETUNREACH. Source: https://man7.org/linux/man-pages/man2/accept.2.html

WASI implementations have two options to handle this:

Optionally log it and then skip over non-fatal errors returned by accept. Guest code never gets to see these failures. Or:
Synthesize a tcp-socket resource that exposes the error when attempting to send or receive on it. Guest code then sees these failures as regular I/O errors.

In either case, the stream returned by this listen method remains operational.

WASI requires listen to perform an implicit bind if the socket has not already been bound. Not all platforms (notably Windows) exhibit this behavior out of the box. On platforms that require it, the WASI implementation can emulate this behavior by performing the bind itself if the guest hasn't already done so.

References

F send

send: func(data: stream<u8>) -> future<result<_, error-code>>;

Transmit data to peer.

The caller should close the stream when it has no more data to send to the peer. Under normal circumstances this will cause a FIN packet to be sent out. Closing the stream is equivalent to calling shutdown(SHUT_WR) in POSIX.

This function may be called at most once and returns once the full contents of the stream are transmitted or an error is encountered.

Typical errors

invalid-state: The socket is not in the connected state. (ENOTCONN)
invalid-state: send has already been called on this socket.
connection-broken: The connection is not writable anymore. (EPIPE, ECONNABORTED on Windows)
connection-reset: The connection was reset. (ECONNRESET)
remote-unreachable: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)

References

F receive

receive: func() -> tuple<stream<u8>, future<result<_, error-code>>>;

Read data from peer.

Returns a stream of data sent by the peer. The implementation drops the stream once no more data is available. At that point, the returned future resolves to:

ok after a graceful shutdown from the peer (i.e. a FIN packet), or
err if the socket was closed abnormally.

receive may be called only once per socket. Subsequent calls return a closed stream and a future resolved to err(invalid-state).

If the caller is not expecting to receive any more data from the peer, they should drop the stream. Any data still in the receive queue will be discarded. This is equivalent to calling shutdown(SHUT_RD) in POSIX.

Typical errors

invalid-state: The socket is not in the connected state. (ENOTCONN)
invalid-state: receive has already been called on this socket.
connection-reset: The connection was reset. (ECONNRESET)
remote-unreachable: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)

References

F get-local-address

get-local-address: func() -> result<ip-socket-address, error-code>;

Get the bound local address.

POSIX mentions:

If the socket has not been bound to a local name, the value stored in the object pointed to by address is unspecified.

WASI is stricter and requires get-local-address to return invalid-state when the socket hasn't been bound yet.

Typical errors

invalid-state: The socket is not bound to any local address.

References

F get-remote-address

get-remote-address: func() -> result<ip-socket-address, error-code>;

Get the remote address.

Typical errors

invalid-state: The socket is not connected to a remote address. (ENOTCONN)

References

F get-is-listening

get-is-listening: func() -> bool;

Whether the socket is in the listening state.

Equivalent to the SO_ACCEPTCONN socket option.

F get-address-family

get-address-family: func() -> ip-address-family;

Whether this is a IPv4 or IPv6 socket.

This is the value passed to the constructor.

Equivalent to the SO_DOMAIN socket option.

F set-listen-backlog-size

set-listen-backlog-size: func(value: u64) -> result<_, error-code>;

Hints the desired listen queue size. Implementations are free to ignore this.

If the provided value is 0, an invalid-argument error is returned. Any other value will never cause an error, but it might be silently clamped and/or rounded.

Typical errors

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 in the connecting or connected state.

F get-keep-alive-enabled

get-keep-alive-enabled: func() -> result<bool, error-code>;

Enables or disables keepalive.

The keepalive behavior can be adjusted using:

keep-alive-idle-time
keep-alive-interval
keep-alive-count These properties can be configured while keep-alive-enabled is false, but only come into effect when keep-alive-enabled is true.

Equivalent to the SO_KEEPALIVE socket option.

F set-keep-alive-enabled

set-keep-alive-enabled: func(value: bool) -> result<_, error-code>;

F get-keep-alive-idle-time

get-keep-alive-idle-time: func() -> result<duration, error-code>;

Amount of time the connection has to be idle before TCP starts sending keepalive packets.

If the provided value is 0, an invalid-argument error is returned. All other values are accepted without error, but may be clamped or rounded. As a result, the value read back from this setting may differ from the value that was set.

Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)

Typical errors

invalid-argument: (set) The provided value was 0.

F set-keep-alive-idle-time

set-keep-alive-idle-time: func(value: duration) -> result<_, error-code>;

F get-keep-alive-interval

get-keep-alive-interval: func() -> result<duration, error-code>;

The time between keepalive packets.

If the provided value is 0, an invalid-argument error is returned. All other values are accepted without error, but may be clamped or rounded. As a result, the value read back from this setting may differ from the value that was set.

Equivalent to the TCP_KEEPINTVL socket option.

Typical errors

invalid-argument: (set) The provided value was 0.

F set-keep-alive-interval

set-keep-alive-interval: func(value: duration) -> result<_, error-code>;

F get-keep-alive-count

get-keep-alive-count: func() -> result<u32, error-code>;

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. All other values are accepted without error, but may be clamped or rounded. As a result, the value read back from this setting may differ from the value that was set.

Equivalent to the TCP_KEEPCNT socket option.

Typical errors

invalid-argument: (set) The provided value was 0.

F set-keep-alive-count

set-keep-alive-count: func(value: u32) -> result<_, error-code>;

F get-hop-limit

get-hop-limit: func() -> result<u8, error-code>;

Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.

If the provided value is 0, an invalid-argument error is returned.

Typical errors

invalid-argument: (set) The TTL value must be 1 or higher.

F set-hop-limit

set-hop-limit: func(value: u8) -> result<_, error-code>;

F get-receive-buffer-size

get-receive-buffer-size: func() -> result<u64, error-code>;

Kernel buffer space reserved for sending/receiving on this socket. Implementations usually treat this as a cap the buffer can grow to, rather than allocating the full amount immediately.

If the provided value is 0, an invalid-argument error is returned. All other values are accepted without error, but may be clamped or rounded. As a result, the value read back from this setting may differ from the value that was set.

This is only a performance hint. The implementation may ignore it or tweak it based on real traffic patterns. Linux and macOS appear to behave differently depending on whether a buffer size was explicitly set. When set, they tend to honor it; when not set, they dynamically adjust the buffer size as the connection progresses. This is especially noticeable when comparing the values from before and after connection establishment.

Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.

Typical errors

invalid-argument: (set) The provided value was 0.

F set-receive-buffer-size

set-receive-buffer-size: func(value: u64) -> result<_, error-code>;

F get-send-buffer-size

get-send-buffer-size: func() -> result<u64, error-code>;

F set-send-buffer-size

set-send-buffer-size: func(value: u64) -> result<_, error-code>;

F create

create: func(address-family: ip-address-family) -> result<tcp-socket, error-code>;

Create a new TCP socket.

Similar to socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP) in POSIX. On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.

Unlike POSIX, WASI sockets have no notion of a socket-level O_NONBLOCK flag. Instead they fully rely on the Component Model's async support.

Typical errors

not-supported: The address-family is not supported. (EAFNOSUPPORT)