Trait wasmtime_wasi::bindings::sync::sockets::tcp::HostTcpSocket
source · pub trait HostTcpSocket {
Show 29 methods
// 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§
sourcefn start_bind(
&mut self,
self_: Resource<TcpSocket>,
network: Resource<Network>,
local_address: IpSocketAddress,
) -> Result<(), SocketError>
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.
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
: Thelocal-address
has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)invalid-argument
:local-address
is not a unicast address. (EINVAL)invalid-argument
:local-address
is an IPv4-mapped IPv6 address. (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 thenetwork
can bind to. (EADDRNOTAVAIL)not-in-progress
: Abind
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.
Unlike in POSIX, in WASI the bind operation is async. This enables
interactive WASI hosts to inject permission prompts. Runtimes that
don’t want to make use of this ability can simply call the native
bind
as part of either start-bind
or finish-bind
.
§References
fn finish_bind(&mut self, self_: Resource<TcpSocket>) -> Result<(), SocketError>
sourcefn start_connect(
&mut self,
self_: Resource<TcpSocket>,
network: Resource<Network>,
remote_address: IpSocketAddress,
) -> 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
connected
state. - a pair of streams is returned that can be used to read & write to the connection
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
: Theremote-address
has the wrong address family. (EAFNOSUPPORT)invalid-argument
:remote-address
is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)invalid-argument
:remote-address
is an IPv4-mapped IPv6 address. (EINVAL, EADDRNOTAVAIL on Illumos)invalid-argument
: The IP address inremote-address
is set to INADDR_ANY (0.0.0.0
/::
). (EADDRNOTAVAIL on Windows)invalid-argument
: The port inremote-address
is set to 0. (EADDRNOTAVAIL on Windows)invalid-argument
: The socket is already attached to a different network. Thenetwork
passed toconnect
must be identical to the one passed tobind
.invalid-state
: The socket is already in theconnected
state. (EISCONN)invalid-state
: The socket is already in thelistening
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)not-in-progress
: A connect operation is not in progress.would-block
: Can’t finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
§Implementors note
The POSIX equivalent of start-connect
is the regular connect
syscall.
Because all WASI sockets are non-blocking this is expected to return
EINPROGRESS, which should be translated to ok()
in WASI.
The POSIX equivalent of finish-connect
is a poll
for event POLLOUT
with a timeout of 0 on the socket descriptor. Followed by a check for
the SO_ERROR
socket option, in case the poll signaled readiness.
§References
fn finish_connect( &mut self, self_: Resource<TcpSocket>, ) -> Result<(Resource<InputStream>, Resource<OutputStream>), SocketError>
sourcefn start_listen(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<(), SocketError>
fn start_listen( &mut self, self_: Resource<TcpSocket>, ) -> Result<(), SocketError>
Start listening for new connections.
Transitions the socket into the listening
state.
Unlike POSIX, the socket must already be explicitly bound.
§Typical errors
invalid-state
: The socket is not bound to any local address. (EDESTADDRREQ)invalid-state
: The socket is already in theconnected
state. (EISCONN, EINVAL on BSD)invalid-state
: The socket is already in thelistening
state.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)
§Implementors note
Unlike in POSIX, in WASI the listen operation is async. This enables
interactive WASI hosts to inject permission prompts. Runtimes that
don’t want to make use of this ability can simply call the native
listen
as part of either start-listen
or finish-listen
.
§References
fn finish_listen( &mut self, self_: Resource<TcpSocket>, ) -> Result<(), SocketError>
sourcefn accept(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<(Resource<TcpSocket>, Resource<InputStream>, Resource<OutputStream>), 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 connected
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 thelistening
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
sourcefn local_address(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<IpSocketAddress, SocketError>
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
sourcefn remote_address(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<IpSocketAddress, SocketError>
fn remote_address( &mut self, self_: Resource<TcpSocket>, ) -> Result<IpSocketAddress, SocketError>
sourcefn is_listening(&mut self, self_: Resource<TcpSocket>) -> Result<bool>
fn is_listening(&mut self, self_: Resource<TcpSocket>) -> Result<bool>
Whether the socket is in the listening
state.
Equivalent to the SO_ACCEPTCONN socket option.
sourcefn address_family(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<IpAddressFamily>
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.
sourcefn set_listen_backlog_size(
&mut self,
self_: Resource<TcpSocket>,
value: u64,
) -> Result<(), SocketError>
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 theconnect-in-progress
orconnected
state.
sourcefn keep_alive_enabled(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<bool, SocketError>
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 whilekeep-alive-enabled
is false, but only come into effect whenkeep-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>
sourcefn keep_alive_idle_time(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<Duration, 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>
sourcefn keep_alive_interval(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<Duration, 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>
sourcefn keep_alive_count(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<u32, 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>
sourcefn hop_limit(&mut self, self_: Resource<TcpSocket>) -> Result<u8, 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.
fn set_hop_limit( &mut self, self_: Resource<TcpSocket>, value: u8, ) -> Result<(), SocketError>
sourcefn receive_buffer_size(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<u64, 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.
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>
sourcefn subscribe(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<Resource<Pollable>>
fn subscribe( &mut self, self_: Resource<TcpSocket>, ) -> Result<Resource<Pollable>>
Create a pollable
which can be used to poll for, or block on,
completion of any of the asynchronous operations of this socket.
When finish-bind
, finish-listen
, finish-connect
or accept
return error(would-block)
, this pollable can be used to wait for
their success or failure, after which the method can be retried.
The pollable is not limited to the async operation that happens to be
in progress at the time of calling subscribe
(if any). Theoretically,
subscribe
only has to be called once per socket and can then be
(re)used for the remainder of the socket’s lifetime.
See https://github.com/WebAssembly/wasi-sockets/blob/main/TcpSocketOperationalSemantics.md#pollable-readiness for more information.
Note: this function is here for WASI Preview2 only.
It’s planned to be removed when future
is natively supported in Preview3.
sourcefn shutdown(
&mut self,
self_: Resource<TcpSocket>,
shutdown_type: ShutdownType,
) -> Result<(), SocketError>
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. Theinput-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. Theoutput-stream
associated with this socket will be closed and a FIN packet will be sent.both
: Same effect asreceive
&send
combined.
This function is idempotent; shutting 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 theconnected
state. (ENOTCONN)
§References
fn drop(&mut self, rep: Resource<TcpSocket>) -> Result<()>
Implementations on Foreign Types§
source§impl<_T: HostTcpSocket + ?Sized> HostTcpSocket for &mut _T
impl<_T: HostTcpSocket + ?Sized> HostTcpSocket for &mut _T
source§fn start_bind(
&mut self,
self_: Resource<TcpSocket>,
network: Resource<Network>,
local_address: IpSocketAddress,
) -> Result<(), SocketError>
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.
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
: Thelocal-address
has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)invalid-argument
:local-address
is not a unicast address. (EINVAL)invalid-argument
:local-address
is an IPv4-mapped IPv6 address. (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 thenetwork
can bind to. (EADDRNOTAVAIL)not-in-progress
: Abind
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.
Unlike in POSIX, in WASI the bind operation is async. This enables
interactive WASI hosts to inject permission prompts. Runtimes that
don’t want to make use of this ability can simply call the native
bind
as part of either start-bind
or finish-bind
.
§References
source§fn start_connect(
&mut self,
self_: Resource<TcpSocket>,
network: Resource<Network>,
remote_address: IpSocketAddress,
) -> 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
connected
state. - a pair of streams is returned that can be used to read & write to the connection
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
: Theremote-address
has the wrong address family. (EAFNOSUPPORT)invalid-argument
:remote-address
is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)invalid-argument
:remote-address
is an IPv4-mapped IPv6 address. (EINVAL, EADDRNOTAVAIL on Illumos)invalid-argument
: The IP address inremote-address
is set to INADDR_ANY (0.0.0.0
/::
). (EADDRNOTAVAIL on Windows)invalid-argument
: The port inremote-address
is set to 0. (EADDRNOTAVAIL on Windows)invalid-argument
: The socket is already attached to a different network. Thenetwork
passed toconnect
must be identical to the one passed tobind
.invalid-state
: The socket is already in theconnected
state. (EISCONN)invalid-state
: The socket is already in thelistening
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)not-in-progress
: A connect operation is not in progress.would-block
: Can’t finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
§Implementors note
The POSIX equivalent of start-connect
is the regular connect
syscall.
Because all WASI sockets are non-blocking this is expected to return
EINPROGRESS, which should be translated to ok()
in WASI.
The POSIX equivalent of finish-connect
is a poll
for event POLLOUT
with a timeout of 0 on the socket descriptor. Followed by a check for
the SO_ERROR
socket option, in case the poll signaled readiness.
§References
source§fn start_listen(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<(), SocketError>
fn start_listen( &mut self, self_: Resource<TcpSocket>, ) -> Result<(), SocketError>
Start listening for new connections.
Transitions the socket into the listening
state.
Unlike POSIX, the socket must already be explicitly bound.
§Typical errors
invalid-state
: The socket is not bound to any local address. (EDESTADDRREQ)invalid-state
: The socket is already in theconnected
state. (EISCONN, EINVAL on BSD)invalid-state
: The socket is already in thelistening
state.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)
§Implementors note
Unlike in POSIX, in WASI the listen operation is async. This enables
interactive WASI hosts to inject permission prompts. Runtimes that
don’t want to make use of this ability can simply call the native
listen
as part of either start-listen
or finish-listen
.
§References
source§fn accept(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<(Resource<TcpSocket>, Resource<InputStream>, Resource<OutputStream>), 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 connected
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 thelistening
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
source§fn local_address(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<IpSocketAddress, SocketError>
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
source§fn remote_address(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<IpSocketAddress, SocketError>
fn remote_address( &mut self, self_: Resource<TcpSocket>, ) -> Result<IpSocketAddress, SocketError>
source§fn is_listening(&mut self, self_: Resource<TcpSocket>) -> Result<bool>
fn is_listening(&mut self, self_: Resource<TcpSocket>) -> Result<bool>
Whether the socket is in the listening
state.
Equivalent to the SO_ACCEPTCONN socket option.
source§fn address_family(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<IpAddressFamily>
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.
source§fn set_listen_backlog_size(
&mut self,
self_: Resource<TcpSocket>,
value: u64,
) -> Result<(), SocketError>
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 theconnect-in-progress
orconnected
state.
source§fn keep_alive_enabled(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<bool, SocketError>
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 whilekeep-alive-enabled
is false, but only come into effect whenkeep-alive-enabled
is true.
Equivalent to the SO_KEEPALIVE socket option.
source§fn keep_alive_idle_time(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<Duration, 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.
source§fn keep_alive_interval(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<Duration, 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.
source§fn keep_alive_count(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<u32, 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.
source§fn hop_limit(&mut self, self_: Resource<TcpSocket>) -> Result<u8, 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.
source§fn receive_buffer_size(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<u64, 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.
source§fn subscribe(
&mut self,
self_: Resource<TcpSocket>,
) -> Result<Resource<Pollable>>
fn subscribe( &mut self, self_: Resource<TcpSocket>, ) -> Result<Resource<Pollable>>
Create a pollable
which can be used to poll for, or block on,
completion of any of the asynchronous operations of this socket.
When finish-bind
, finish-listen
, finish-connect
or accept
return error(would-block)
, this pollable can be used to wait for
their success or failure, after which the method can be retried.
The pollable is not limited to the async operation that happens to be
in progress at the time of calling subscribe
(if any). Theoretically,
subscribe
only has to be called once per socket and can then be
(re)used for the remainder of the socket’s lifetime.
See https://github.com/WebAssembly/wasi-sockets/blob/main/TcpSocketOperationalSemantics.md#pollable-readiness for more information.
Note: this function is here for WASI Preview2 only.
It’s planned to be removed when future
is natively supported in Preview3.
source§fn shutdown(
&mut self,
self_: Resource<TcpSocket>,
shutdown_type: ShutdownType,
) -> Result<(), SocketError>
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. Theinput-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. Theoutput-stream
associated with this socket will be closed and a FIN packet will be sent.both
: Same effect asreceive
&send
combined.
This function is idempotent; shutting 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 theconnected
state. (ENOTCONN)