Trait HostTcpSocket 

pub trait HostTcpSocket: Send {
    // Required methods
    fn create(
        &mut self,
        address_family: IpAddressFamily,
    ) -> Result<Resource<TcpSocket>, SocketError>;
    fn bind(
        &mut self,
        self_: Resource<TcpSocket>,
        local_address: IpSocketAddress,
    ) -> impl Future<Output = Result<(), SocketError>> + Send;
    fn get_local_address(
        &mut self,
        self_: Resource<TcpSocket>,
    ) -> Result<IpSocketAddress, SocketError>;
    fn get_remote_address(
        &mut self,
        self_: Resource<TcpSocket>,
    ) -> Result<IpSocketAddress, SocketError>;
    fn get_is_listening(&mut self, self_: Resource<TcpSocket>) -> Result<bool>;
    fn get_address_family(
        &mut self,
        self_: Resource<TcpSocket>,
    ) -> Result<IpAddressFamily>;
    fn set_listen_backlog_size(
        &mut self,
        self_: Resource<TcpSocket>,
        value: u64,
    ) -> Result<(), SocketError>;
    fn get_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 get_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 get_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 get_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 get_hop_limit(
        &mut self,
        self_: Resource<TcpSocket>,
    ) -> Result<u8, SocketError>;
    fn set_hop_limit(
        &mut self,
        self_: Resource<TcpSocket>,
        value: u8,
    ) -> Result<(), SocketError>;
    fn get_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 get_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 drop(&mut self, rep: Resource<TcpSocket>) -> Result<()>;
}

Available on crate feature p3 only.

Required Methods

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

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)

References

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

fn bind( &mut self, self_: Resource<TcpSocket>, local_address: IpSocketAddress, ) -> impl Future<Output = Result<(), SocketError>> + Send

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

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

• 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 get_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 get_is_listening(&mut self, self_: Resource<TcpSocket>) -> Result<bool>

Whether the socket is in the listening state.

Equivalent to the SO_ACCEPTCONN socket option.

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

Whether this is a IPv4 or IPv6 socket.

This is the value passed to the constructor.

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

fn get_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 get_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. 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.

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

fn get_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. 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.

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

fn get_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. 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.

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

fn get_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.

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

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

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.

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

fn get_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 drop(&mut self, rep: Resource<TcpSocket>) -> Result<()>

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<_T: HostTcpSocket + ?Sized + Send> HostTcpSocket for &mut _T

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

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)

References

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

fn bind( &mut self, self_: Resource<TcpSocket>, local_address: IpSocketAddress, ) -> impl Future<Output = Result<(), SocketError>> + Send

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

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

• 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 get_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 get_is_listening(&mut self, self_: Resource<TcpSocket>) -> Result<bool>

Whether the socket is in the listening state.

Equivalent to the SO_ACCEPTCONN socket option.

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

Whether this is a IPv4 or IPv6 socket.

This is the value passed to the constructor.

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

fn get_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 get_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. 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.

fn get_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. 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.

fn get_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. 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.

fn get_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.

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

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.

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

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

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

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

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

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

fn get_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 drop(&mut self, rep: Resource<TcpSocket>) -> Result<()>

Implementors

impl HostTcpSocket for WasiSocketsCtxView<'_>