Connection

What this module is responsible for

The Connection component manages the lifecycle and communication between a client and a Booblik broker. It is responsible for establishing asynchronous connections, handling the framing of requests and responses, managing data transfer efficiency via zero-copy mechanisms, and ensuring that protocol errors are correctly distinguished from connection-level failures.

Diagram

Connection.ConnectAsync

The asynchronous establishment of a connection to a broker is the entry point for client interaction, as seen in ConnectionTests.cs:22 and connection.test.js:19. This process initializes the underlying transport and prepares the client to send framed requests.

AckPolicy.None

The behavior of asynchronous production when no response is expected from the broker is governed by AckPolicy.None. When this policy is used, the client does not wait for a response from the broker, which is verified by ensuring the produce task returns null or completes without waiting for a broker acknowledgement (connection.test.js:46 and ServerTest.kt:65).

ProtocolException and ProtocolError

Handling of malformed frames and truncated responses during decoding is critical for stability. A response that is cut short by a broker restart is treated as a ProtocolException rather than a standard decoding error (ConnectionTests.cs:102), and such malformed data must trigger a ProtocolError to prevent the caller from receiving invalid state (connection.test.js:88).

SocketChannel and transferTo

The mechanics of zero-copy data transfer rely on the transferTo method, which requires the underlying object to be a real SocketChannel to utilize the JDK's direct sendfile path (SendfileTest.kt:72). If the connection is wrapped in a decorator (like a metrics or TLS layer), the direct path is lost, even though the resulting bytes remain identical (SendfileTest.kt:101).

Partial Frame Assembly

The system is designed to handle fragmented network traffic through robust assembly logic:

• Split Packets: A frame split across two packets is correctly assembled once the remaining bytes arrive (PartialFrameTest.kt:40).
• Byte-at-a-time: Data delivered one byte at a time is still successfully assembled into a single request (PartialFrameTest.kt:65).
• Absurd Lengths: If a frame specifies an absurdly large length, the broker must drop the connection rather than attempting to allocate massive amounts of memory (PartialFrameTest.kt:112).

Broker Refusals

The distinction between protocol errors that close a connection and errors that allow connection reuse is vital for reliability. A refusal (such as UnknownTopicOrPartition) is a protocol-level error that does not close the connection if the framing remains intact (ConnectionTests.cs:53), whereas a frame length out of range is a framing error that must close the connection (ConnectionTests.cs:61).

Key files

Behaviour that すれthought

• AckPolicy.None results in the client not receiving an offset, as the broker sends nothing back (connection.test.js:48).
• A ProtocolException is specifically used to signal that a response was truncated, distinguishing it from a standard RangeError during decoding (ConnectionTests.cs:102).
• The transferTo path is highly sensitive to object wrapping; wrapping a SocketChannel in a decorator can silently disable zero-copy optimizations (SendfileTest.kt:40).