Summary

Make readCancelConfirmation respect context cancellation so QueryContext callers are not blocked indefinitely when the network is down.

Attribution

This fix implements the approach proposed by @tiwo in #160 (with @vasily-kirichenko's correction to use value type assertion doneStruct instead of pointer *doneStruct).

Problem

When a query is cancelled via context (e.g. QueryContext with a timeout), the driver sends a cancellation request to the server and then calls readCancelConfirmation to wait for the server's acknowledgement. This function uses for range tokChan which blocks until:

1. A doneStruct with doneAttn is received (success), or
2. The channel is closed

When the network is down, processSingleResponse blocks on sess.buf reads and never closes tokChan. This causes readCancelConfirmation to block forever, even though the caller's context has already been cancelled.

Users reported that QueryContext with a deadline would hang permanently instead of returning when the network connection was lost (#160).

Fix

Change readCancelConfirmation to accept a context.Context and return a cancelConfirmationResult enum (received/channelClosed/unavailable) instead of bool. It uses a double-select pattern: first non-blocking to prioritize buffered tokens, then blocking on both ctx.Done() and tokChan.

In nextToken(), a drainCtx with a 5-second timeout is created (since t.ctx is already cancelled at that point) and passed to readCancelConfirmation for the first drain attempt. When the first drain returns channelClosed (current response had no DONE_ATTN), a second response reader is started with t.ctx (already cancelled) so that processSingleResponse's ReturnMessageEnqueue calls return immediately via ctx.Done() — preventing goroutine stalls on a full message queue. A fresh drainCtx2 is created for the second readCancelConfirmation call so the first attempt's elapsed time does not consume the second attempt's timeout budget. When either drain returns unavailable, a ServerError is returned with diagnostic context (phase and underlying cause).

Tests

Added 9 tests:

Unit tests for readCancelConfirmation (token_unit_test.go):

• TestReadCancelConfirmation_Success - confirms doneAttn token returns received
• TestReadCancelConfirmation_ChannelClosedWithoutConfirmation - closed channel returns channelClosed
• TestReadCancelConfirmation_ContextCancelled - cancelled context returns unavailable
• TestReadCancelConfirmation_SkipsNonAttnTokens - non-done and done-without-attn tokens are skipped
• TestReadCancelConfirmation_PrioritizesBufferedTokenOverCancelledContext - buffered attn token wins over cancelled ctx
• TestReadCancelConfirmation_ErrorTokenIsUnavailable - error on channel returns unavailable

Direct tests for nextToken cancel drain (token_test.go):

• TestNextToken_CancelDrainCurrentResponseConfirmationReturnsContextError - current-response doneAttn returns context.Canceled without starting a second response
• TestNextToken_CancelDrainUnavailableDoesNotStartSecondResponse - error token short-circuits without spawning a second processSingleResponse
• TestNextToken_CancelDrainClosedChannelStartsSecondResponse - closed channel proceeds to the second response and finds doneAttn confirmation

Goroutine Lifecycle

When cancel-drain times out, processSingleResponse may still be running (blocked on a network read). The ServerError return marks the connection as bad. When the connection pool closes the underlying net.Conn, the blocked read unblocks with an error and the goroutine exits. This is the standard cleanup mechanism for bad connections.

Risk

Low. The only behavioral change is that cancellation drain is now bounded by a 5-second timeout per attempt. The function still processes all tokens identically when the context is not cancelled. The connection is marked bad (ServerError) if drain times out, which causes cleanup of any outstanding goroutines when the connection is closed.

Fixes #160