Conn

What this module is responsible for

The Conn type is the fundamental transport layer for the booblik Go client. It manages a single TCP connection to a broker and handles the low-level framing of the wire protocol. It is responsible for serializing request headers, managing correlation IDs to ensure request-response integrity, and enforcing protocol-level constraints like maximum frame sizes.

Diagram

The Conn lifecycle and Dial

A connection is established using the Dial function, which takes a context.Context to bound the initial connection attempt (booblik.go:85-94). Once established, the connection is not safe for concurrent use because requests and responses are matched by a strictly incrementing correlation ID (booblik.go:75-77). To ensure low latency for the small requests typical of this protocol, the client relies on TCP_NODELAY being enabled by default in Go (booblik.go:91-93).

Request-Response matching via correlation

To ensure that a response is matched to the correct caller, the Conn maintains an internal correlation counter (booblik.go:80). Every time send is called, the correlation is incremented and included in the request header (booblik.go:125-132). During the receive phase, the client explicitly checks that the correlation ID returned by the broker matches the one expected for that specific request; if they do not match, the client returns an error to prevent one caller from receiving another's data (booblik.go:162-164).

Context-driven deadlines and withContext

Since Go's standard socket operations do not natively support context.Context for interruption, Conn implements a withContext method to bridge this gap (booblik.go:103-122). This method works by moving the connection's deadline into the past to interrupt blocking operations if the context is cancelled or reaches its deadline (booblik.go:104-114). It returns an undo function that restores the deadline once the exchange is complete (booblik.go:118-121).

The receive mechanism and frame validation

The receive method performs strict validation on incoming data to protect the client from malformed or malicious responses (booblik.go:141-168). The validation steps include:

• Reading the 4-byte length prefix (booblik.go:144-146).
• Ensuring the length is within the bounds of responseHeaderBytes and maxFrameBytes (booblik.go:147-149).
• Verifying the correlation ID matches the expected value (booblik.go:162-164).
• Checking that the response code is CodeNone (booblik.go:165-167).

Error handling and connection stability

The client distinguishes between protocol errors and transport errors to maintain connection stability (booblik_test.go:74-90).

• Usable Errors: Errors like UNKNOWN_TOPIC_OR_PARTITION are considered protocol-level refusals; because the framing remains intact, the connection remains usable for subsequent requests (booblik_test.go:76-88).
• Fatal Errors: If a response frame length is out of range, the connection is effectively compromised and cannot be safely reused (booblik.go:147-149).

Testing AckNone and response timeouts

The client must handle the AckNone policy, where the broker does not send a response (booblik.go:50-52). Tests verify that when AckNone is used, the Produce call returns immediately with a nil result and no error, rather than waiting for a response that will never arrive (booblik_test.go:57-72).

Key files

Behaviour that surprises

• Conn.send increments the correlation ID internally, meaning the caller does not manage the sequence of IDs (booblik.go:125).
• Using AckNone in a Produce call results in a nil ProduceResult because there is no response to parse (booblik.go:262-263).
• A Conn is not thread-safe; sharing a single Conn between goroutines will cause them to read each other's responses due to the shared correlation state (booblik.go:75-77).