tcp.wit

default interface tcp {
	use io.streams.{input-stream, output-stream}
	use poll.poll.{pollable}
	use pkg.network.{network, error, ip-socket-address, ip-address-family}

	/// A TCP socket handle.
	type tcp-socket = u32
	

	enum shutdown-type {
		/// Similar to `SHUT_RD` in POSIX.
		receive,

		/// Similar to `SHUT_WR` in POSIX.
		send,

		/// Similar to `SHUT_RDWR` in POSIX.
		both,
	}


	/// 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.
	/// 
	/// Fails when:
	/// - the socket is already bound.
	/// 
	/// References
	/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
	/// - <https://man7.org/linux/man-pages/man2/bind.2.html>
	bind: func(this: tcp-socket, network: network, local-address: ip-socket-address) -> result<_, error>

	/// 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
	/// 
	/// Fails when:
	/// - the socket is already bound to a different network.
	/// - the provided network does not allow connections to the specified endpoint.
	/// - the socket is already in the Connection or Listener state.
	/// - either the remote IP address or port is 0.
	/// 
	/// References
	/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>
	/// - <https://man7.org/linux/man-pages/man2/connect.2.html>
	connect: func(this: tcp-socket, network: network, remote-address: ip-socket-address) -> result<tuple<input-stream, output-stream>, error>

	/// Start listening for new connections.
	/// 
	/// Transitions the socket into the Listener state.
	/// 
	/// Fails when:
	/// - the socket is already bound to a different network.
	/// - the provided network does not allow listening on the specified address.
	/// - the socket is already in the Connection or Listener state.
	///
	///  References
	/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html>
	/// - <https://man7.org/linux/man-pages/man2/listen.2.html>
	listen: func(this: tcp-socket, network: network) -> result<_, error>

	/// Accept a new client socket.
	/// 
	/// The returned socket is bound and in the Connection state.
	/// 
	/// 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.
	/// 
	/// Fails when this socket is not in the Listening state.
	/// 
	/// References:
	/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html>
	/// - <https://man7.org/linux/man-pages/man2/accept.2.html>
	accept: func(this: tcp-socket) -> result<tuple<tcp-socket, input-stream, output-stream>, error>

	/// Get the bound local address.
	/// 
	/// Returns an error if the socket is not bound.
	/// 
	/// References
	/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html>
	/// - <https://man7.org/linux/man-pages/man2/getsockname.2.html>
	local-address: func(this: tcp-socket) -> result<ip-socket-address, error>

	/// Get the bound remote address.
	/// 
	/// Fails when the socket is not in the Connection state.
	/// 
	/// References
	/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html>
	/// - <https://man7.org/linux/man-pages/man2/getpeername.2.html>
	remote-address: func(this: tcp-socket) -> result<ip-socket-address, error>

	/// Whether this is a IPv4 or IPv6 socket.
	/// 
	/// Equivalent to the SO_DOMAIN socket option.
	address-family: func(this: tcp-socket) -> result<ip-address-family, error>
	
	/// Whether IPv4 compatibility (dual-stack) mode is disabled or not.
	/// Implementations are not required to support dual-stack mode. Calling `set-ipv6-only(false)` might fail.
	/// 
	/// Fails when called on an IPv4 socket.
	/// 
	/// Equivalent to the IPV6_V6ONLY socket option.
	ipv6-only: func(this: tcp-socket) -> result<bool, error>
	set-ipv6-only: func(this: tcp-socket, value: bool) -> result<_, error>

	/// Hints the desired listen queue size. Implementations are free to ignore this.
	set-listen-backlog-size: func(this: tcp-socket, value: u64) -> result<_, error>

	/// Equivalent to the SO_KEEPALIVE socket option.
	keep-alive: func(this: tcp-socket) -> result<bool, error>
	set-keep-alive: func(this: tcp-socket, value: bool) -> result<_, error>

	/// Equivalent to the TCP_NODELAY socket option.
	no-delay: func(this: tcp-socket) -> result<bool, error>
	set-no-delay: func(this: tcp-socket, value: bool) -> result<_, error>
	
	/// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
	unicast-hop-limit: func(this: tcp-socket) -> result<u8, error>
	set-unicast-hop-limit: func(this: tcp-socket, value: u8) -> result<_, error>

	/// The kernel buffer space reserved for sends/receives on this socket.
	/// 
	/// Note #1: an implementation may choose to cap or round the buffer size when setting the value.
	/// 	In other words, after setting a value, reading the same setting back may return a different value.
	/// 
	/// Note #2: there is not necessarily a direct relationship between the kernel buffer size and the bytes of
	/// 	actual data to be sent/received by the application, because the kernel might also use the buffer space
	/// 	for internal metadata structures.
	/// 
	/// Fails when this socket is in the Listening state.
	/// 
	/// Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
	receive-buffer-size: func(this: tcp-socket) -> result<u64, error>
	set-receive-buffer-size: func(this: tcp-socket, value: u64) -> result<_, error>
	send-buffer-size: func(this: tcp-socket) -> result<u64, error>
	set-send-buffer-size: func(this: tcp-socket, value: u64) -> result<_, error>

	/// Get/set the blocking mode of the socket.
	/// 
	/// By default a socket is in "blocking" mode, meaning that any function blocks and waits for its completion.
	/// When switched to "non-blocking" mode, operations that would block return an `again` error. After which
	/// the API consumer is expected to call `subscribe` and wait for completion using the wasi-poll module.
	/// 
	/// Note: these functions are here for WASI Preview2 only.
	/// They're planned to be removed when `future` is natively supported in Preview3.
	non-blocking: func(this: tcp-socket) -> result<bool, error>
	set-non-blocking: func(this: tcp-socket, value: bool) -> result<_, error>

	/// 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.
	subscribe: func(this: tcp-socket) -> pollable

	/// Gracefully shut down the connection.
	/// 
	/// - 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 the socket.
	/// 
	/// Fails when the socket is not in the Connection state.
	/// 
	/// References
	/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html>
	/// - <https://man7.org/linux/man-pages/man2/shutdown.2.html>
	shutdown: func(this: tcp-socket, shutdown-type: shutdown-type) -> result<_, error>

	/// Dispose of the specified `tcp-socket`, after which it may no longer be used.
	/// 
	/// Note: this function is scheduled to be removed when Resources are natively supported in Wit.
	drop-tcp-socket: func(this: tcp-socket)
}