Socket

What this module is responsible for

The Socket class in the booblik-native module provides a low-level, blocking TCP implementation using POSIX primitives. It serves as the foundation for native clients, handling the raw mechanics of host resolution, connection establishment, and reliable byte transmission.

Diagram

Socket lifecycle and connection establishment

The connection process begins with the connect factory method, which parses the input string to separate the host from the port (Socket.kt:46-50). To ensure cross-platform compatibility between Linux and macOS, the implementation uses getaddrinfo to resolve addresses, which allows it to handle both host names and dotted quads while abstracting away differences in sockaddr layouts (Socket.kt:36-39). The instantiation process involves iterating through the linked list of addrinfo candidates provided by getaddrinfo, attempting to create a socket and connect until a successful descriptor is obtained (Socket.kt:65-72).

TCP_NODELAY and Nagle's algorithm

To optimize performance for the specific traffic pattern of the protocol, the enableNoDelay method is called immediately after a successful connection (Socket.kt:71). This method uses setsockopt with the TCP_NODELAY flag to disable Nagle's algorithm (Socket.kt:94-98). This is critical because the requests are small and involve round trips; failing to set this would cause Nagle's algorithm to add unnecessary delays to each request-response cycle (Socket.kt:86-88).

writeFully and send mechanics

The writeFully method ensures that a ByteArray is completely transmitted over the wire by using a loop that tracks the number of bytes written (Socket.kt:107-108). Inside this loop, the send function is called repeatedly with the remaining buffer length until the entire payload is sent (Socket.kt:110-113). If send returns a value less than or equal to zero, a ConnectionException is thrown, indicating the connection was closed during the transmission (Socket.kt:116).

readFully and connection termination

The readFully method implements a loop to fill a ByteArray of a specific size using the recv function (Socket.kt:126-127). A critical edge case occurs when recv returns zero, which signifies that the broker has performed an orderly close of the connection (Socket.kt:134-135). In such cases, if the requested number of bytes has not been fully received, a ConnectionException is thrown because the caller did not receive the full frame it expected (Socket.kt:136-137).

Socket close

The close method is responsible for the final stage of the socket lifecycle by releasing the underlying system resource (Socket.kt:145-146). It calls the POSIX close function on the stored file descriptor to ensure the socket is properly released back to the operating system (Socket.kt:146).

Key files

Behaviour that surprise

• The connect method in Socket will throw a ConnectionException if it exhausts all addrinfo candidates without successfully establishing a connection (Socket.kt:81).
• In readFully, a return value of zero from recv is treated as a failure if the requested byte count has not been met, rather than being treated as a successful end-of-stream (Socket.kt:136-137).