Go Connection Pooler

This challenge focuses on implementing a connection pooling mechanism in Go for network resources, specifically TCP connections. Efficiently managing and reusing network connections is crucial for high-performance applications, as establishing new connections can be resource-intensive and time-consuming. Your task is to build a robust connection pool that minimizes the overhead of creating and closing connections.

Problem Description

You need to design and implement a ConnectionPool in Go that manages a pool of network connections (e.g., TCP connections to a server). The pool should allow clients to acquire a connection when needed and release it back to the pool when they are finished. The primary goal is to reuse existing connections rather than creating new ones for each request, significantly improving performance.

Key Requirements:

Connection Acquisition: A GetConnection() method should return an available connection from the pool. If no connections are available, it should create a new one (up to a maximum pool size). If the pool is full and no connections are available, GetConnection() should block until a connection becomes available or a timeout occurs.
Connection Release: A ReleaseConnection(conn net.Conn) method should return a used connection back to the pool, making it available for reuse.
Pool Size Management: The pool should have a configurable maximum size to prevent excessive resource consumption.
Connection Validity: The pool should handle situations where a released connection might have become invalid (e.g., network error, server closed the connection). Such connections should not be returned to the pool or should be properly disposed of.
Concurrency Safety: The ConnectionPool must be safe for concurrent access from multiple goroutines.
Graceful Shutdown: A Close() method should gracefully close all connections in the pool and release any associated resources.

Expected Behavior:

When GetConnection() is called and there are available connections, one should be returned immediately.
When GetConnection() is called and the pool is not full, a new connection should be established and returned.
When GetConnection() is called and the pool is full, and all connections are in use, the call should block.
When ReleaseConnection() is called, the connection should be added back to the pool if it's deemed valid.
If a connection is returned to the pool that is no longer valid, it should be discarded and not put back into circulation.
Close() should attempt to close all active connections.

Edge Cases to Consider:

What happens if ReleaseConnection() is called with a nil connection?
How should the pool behave if GetConnection() is called after Close() has been initiated?
Handling network errors during connection establishment and when a connection is returned.
What if a connection is acquired and never released? (This is a client responsibility but good to consider for pool robustness).

Examples

Example 1: Basic Acquisition and Release

Assume a pool is configured with a maximum size of 2 and initially empty.

// Pseudocode Representation
pool := NewConnectionPool("localhost:8080", 2)

// Goroutine 1
conn1 := pool.GetConnection() // Creates and returns a new connection
// ... uses conn1 ...
pool.ReleaseConnection(conn1)

// Goroutine 2
conn2 := pool.GetConnection() // Creates and returns another new connection
// ... uses conn2 ...
pool.ReleaseConnection(conn2)

// Goroutine 3
conn3 := pool.GetConnection() // Reuses conn1 or conn2 if available
// ... uses conn3 ...
pool.ReleaseConnection(conn3)

Output: The sequence of connections returned by GetConnection() would depend on the internal state, but connections are reused.

Explanation: The first two calls to GetConnection() establish new connections. The third call reuses one of the previously established and released connections, demonstrating connection reuse.

Example 2: Blocking and Timeout

Assume a pool is configured with a maximum size of 1, and a connection is already in use.

// Pseudocode Representation
pool := NewConnectionPool("localhost:8080", 1)
connA := pool.GetConnection() // Establishes the only connection

// Goroutine 2 attempts to get a connection
go func() {
  // This call will block
  connB := pool.GetConnection()
  // ...
  pool.ReleaseConnection(connB)
}()

// After some time, Goroutine 1 releases its connection
time.Sleep(100 * time.Millisecond)
pool.ReleaseConnection(connA)

// Now Goroutine 2 can acquire connA (or a new one if connA was deemed invalid)

Output: Goroutine 2 will initially block. Once connA is released, Goroutine 2 will acquire a connection and proceed.

Explanation: Demonstrates that when the pool is at its maximum capacity and all connections are in use, subsequent GetConnection() calls will block until a connection is freed.

Example 3: Invalid Connection Handling

Imagine a scenario where a released connection is detected as invalid.

// Pseudocode Representation
pool := NewConnectionPool("localhost:8080", 2)
conn := pool.GetConnection()
// Simulate an error on the connection, making it invalid
// ... network error occurs ...
pool.ReleaseConnection(conn) // The pool should detect this and discard conn

Output: The invalid connection conn should not be returned by subsequent GetConnection() calls. The pool might establish a new connection to replace it if needed.

Explanation: If a connection is returned in a state that indicates it's no longer usable, the pool should discard it and potentially create a new one to maintain its capacity.

Constraints

The network address for connections will be in the format host:port (e.g., localhost:8080).
Maximum pool size will be an integer greater than or equal to 1.
Connection acquisition calls (GetConnection) should have an optional timeout parameter to prevent indefinite blocking. If the timeout is reached, an error should be returned.
The implementation should be written in Go.
The solution should be reasonably performant, with acquisition and release operations having minimal overhead when connections are available.

Notes

Consider using sync.Mutex or sync.RWMutex for protecting shared data structures within the ConnectionPool.
The net.Conn interface provides methods like Close() and can be used to check for basic connectivity issues. You might need a strategy to proactively check connection health or rely on errors during operation.
Think about how to manage the queue of waiting goroutines when GetConnection() is called and no connections are available.
The Close() method should ensure that no new connections are accepted after it's called and that any pending GetConnection() calls are signaled to stop waiting.