Trait wasmtime_wasi::preview2::bindings::wasi::sockets::tcp::HostTcpSocket

pub trait HostTcpSocket {
    // Required methods
    fn start_bind(
        &mut self,
        self_: Resource<TcpSocket>,
        network: Resource<Network>,
        local_address: IpSocketAddress
    ) -> Result<(), SocketError>;
    fn finish_bind(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<(), SocketError>;
    fn start_connect(
        &mut self,
        self_: Resource<TcpSocket>,
        network: Resource<Network>,
        remote_address: IpSocketAddress
    ) -> Result<(), SocketError>;
    fn finish_connect(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<(Resource<InputStream>, Resource<OutputStream>), SocketError>;
    fn start_listen(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<(), SocketError>;
    fn finish_listen(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<(), SocketError>;
    fn accept(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<(Resource<TcpSocket>, Resource<InputStream>, Resource<OutputStream>), SocketError>;
    fn local_address(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<IpSocketAddress, SocketError>;
    fn remote_address(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<IpSocketAddress, SocketError>;
    fn is_listening(&mut self, self_: Resource<TcpSocket>) -> Result<bool>;
    fn address_family(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<IpAddressFamily>;
    fn set_listen_backlog_size(
        &mut self,
        self_: Resource<TcpSocket>,
        value: u64
    ) -> Result<(), SocketError>;
    fn keep_alive_enabled(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<bool, SocketError>;
    fn set_keep_alive_enabled(
        &mut self,
        self_: Resource<TcpSocket>,
        value: bool
    ) -> Result<(), SocketError>;
    fn keep_alive_idle_time(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<Duration, SocketError>;
    fn set_keep_alive_idle_time(
        &mut self,
        self_: Resource<TcpSocket>,
        value: Duration
    ) -> Result<(), SocketError>;
    fn keep_alive_interval(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<Duration, SocketError>;
    fn set_keep_alive_interval(
        &mut self,
        self_: Resource<TcpSocket>,
        value: Duration
    ) -> Result<(), SocketError>;
    fn keep_alive_count(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<u32, SocketError>;
    fn set_keep_alive_count(
        &mut self,
        self_: Resource<TcpSocket>,
        value: u32
    ) -> Result<(), SocketError>;
    fn hop_limit(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<u8, SocketError>;
    fn set_hop_limit(
        &mut self,
        self_: Resource<TcpSocket>,
        value: u8
    ) -> Result<(), SocketError>;
    fn receive_buffer_size(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<u64, SocketError>;
    fn set_receive_buffer_size(
        &mut self,
        self_: Resource<TcpSocket>,
        value: u64
    ) -> Result<(), SocketError>;
    fn send_buffer_size(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<u64, SocketError>;
    fn set_send_buffer_size(
        &mut self,
        self_: Resource<TcpSocket>,
        value: u64
    ) -> Result<(), SocketError>;
    fn subscribe(
        &mut self,
        self_: Resource<TcpSocket>
    ) -> Result<Resource<Pollable>>;
    fn shutdown(
        &mut self,
        self_: Resource<TcpSocket>,
        shutdown_type: ShutdownType
    ) -> Result<(), SocketError>;
    fn drop(&mut self, rep: Resource<TcpSocket>) -> Result<()>;
}

Required Methods

fn start_bind( &mut self, self_: Resource<TcpSocket>, network: Resource<Network>, local_address: IpSocketAddress ) -> Result<(), SocketError>

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.

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. (EINVAL)
• invalid-state: The socket is already bound. (EINVAL)

Typical finish errors

• address-in-use: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
• address-in-use: Address is already in use. (EADDRINUSE)
• address-not-bindable: local-address is not an address that the network can bind to. (EADDRNOTAVAIL)
• not-in-progress: A bind operation is not in progress.
• would-block: Can’t finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)

Implementors note

When binding to a non-zero port, this 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 entirely.

References

• https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
• https://man7.org/linux/man-pages/man2/bind.2.html
• https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-bind
• https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2&format=html

fn finish_bind(&mut self, self_: Resource<TcpSocket>) -> Result<(), SocketError>

fn start_connect( &mut self, self_: Resource<TcpSocket>, network: Resource<Network>, remote_address: IpSocketAddress ) -> Result<(), SocketError>

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

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

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

• https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html
• https://man7.org/linux/man-pages/man2/connect.2.html
• https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect
• https://man.freebsd.org/cgi/man.cgi?connect

fn finish_connect( &mut self, self_: Resource<TcpSocket> ) -> Result<(Resource<InputStream>, Resource<OutputStream>), SocketError>

fn start_listen( &mut self, self_: Resource<TcpSocket> ) -> Result<(), SocketError>

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

• https://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html
• https://man7.org/linux/man-pages/man2/listen.2.html
• https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-listen
• https://man.freebsd.org/cgi/man.cgi?query=listen&sektion=2

fn finish_listen( &mut self, self_: Resource<TcpSocket> ) -> Result<(), SocketError>

fn accept( &mut self, self_: Resource<TcpSocket> ) -> Result<(Resource<TcpSocket>, Resource<InputStream>, Resource<OutputStream>), SocketError>

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
• keep-alive-enabled
• keep-alive-idle-time
• keep-alive-interval
• keep-alive-count
• hop-limit
• receive-buffer-size
• send-buffer-size

On success, this function returns the newly accepted client socket along with a pair of streams that can be used to read & write to the connection.

Typical errors

• invalid-state: Socket is not in the Listener state. (EINVAL)
• would-block: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)
• connection-aborted: An incoming connection was pending, but was terminated by the client before this listener could accept it. (ECONNABORTED)
• new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)

References

• https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html
• https://man7.org/linux/man-pages/man2/accept.2.html
• https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept
• https://man.freebsd.org/cgi/man.cgi?query=accept&sektion=2

fn local_address( &mut self, self_: Resource<TcpSocket> ) -> Result<IpSocketAddress, SocketError>

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.

Typical errors

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

References

• https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html
• https://man7.org/linux/man-pages/man2/getsockname.2.html
• https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname
• https://man.freebsd.org/cgi/man.cgi?getsockname

fn remote_address( &mut self, self_: Resource<TcpSocket> ) -> Result<IpSocketAddress, SocketError>

Get the remote address.

Typical errors

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

References

• https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html
• https://man7.org/linux/man-pages/man2/getpeername.2.html
• https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername
• https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1

fn is_listening(&mut self, self_: Resource<TcpSocket>) -> Result<bool>

Whether the socket is listening for new connections.

Equivalent to the SO_ACCEPTCONN socket option.

fn address_family( &mut self, self_: Resource<TcpSocket> ) -> Result<IpAddressFamily>

Whether this is a IPv4 or IPv6 socket.

Equivalent to the SO_DOMAIN socket option.

fn set_listen_backlog_size( &mut self, self_: Resource<TcpSocket>, value: u64 ) -> Result<(), SocketError>

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.

fn keep_alive_enabled( &mut self, self_: Resource<TcpSocket> ) -> Result<bool, SocketError>

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.

fn set_keep_alive_enabled( &mut self, self_: Resource<TcpSocket>, value: bool ) -> Result<(), SocketError>

fn keep_alive_idle_time( &mut self, self_: Resource<TcpSocket> ) -> Result<Duration, SocketError>

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

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

fn set_keep_alive_idle_time( &mut self, self_: Resource<TcpSocket>, value: Duration ) -> Result<(), SocketError>

fn keep_alive_interval( &mut self, self_: Resource<TcpSocket> ) -> Result<Duration, SocketError>

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.

fn set_keep_alive_interval( &mut self, self_: Resource<TcpSocket>, value: Duration ) -> Result<(), SocketError>

fn keep_alive_count( &mut self, self_: Resource<TcpSocket> ) -> Result<u32, SocketError>

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.

fn set_keep_alive_count( &mut self, self_: Resource<TcpSocket>, value: u32 ) -> Result<(), SocketError>

fn hop_limit(&mut self, self_: Resource<TcpSocket>) -> Result<u8, SocketError>

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.

fn set_hop_limit( &mut self, self_: Resource<TcpSocket>, value: u8 ) -> Result<(), SocketError>

fn receive_buffer_size( &mut self, self_: Resource<TcpSocket> ) -> Result<u64, SocketError>

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.

fn set_receive_buffer_size( &mut self, self_: Resource<TcpSocket>, value: u64 ) -> Result<(), SocketError>

fn send_buffer_size( &mut self, self_: Resource<TcpSocket> ) -> Result<u64, SocketError>

fn set_send_buffer_size( &mut self, self_: Resource<TcpSocket>, value: u64 ) -> Result<(), SocketError>

fn subscribe( &mut self, self_: Resource<TcpSocket> ) -> Result<Resource<Pollable>>

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.

fn shutdown( &mut self, self_: Resource<TcpSocket>, shutdown_type: ShutdownType ) -> Result<(), SocketError>

Initiate a graceful shutdown.

• receive: The socket is not expecting to receive any data from the peer. The input-stream associated with this socket will be closed. Any data still in the receive queue at time of calling this method will be discarded.
• send: The socket has no more data to send to the peer. The output-stream associated with this socket will be closed and a FIN packet will be sent.
• both: Same effect as receive & send combined.

This function is idempotent. Shutting a down a direction more than once has no effect and returns ok.

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

Typical errors

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

References

• https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html
• https://man7.org/linux/man-pages/man2/shutdown.2.html
• https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-shutdown
• https://man.freebsd.org/cgi/man.cgi?query=shutdown&sektion=2

fn drop(&mut self, rep: Resource<TcpSocket>) -> Result<()>

Implementors

impl<T: WasiView> HostTcpSocket for T