Document the connection pool interface a bit, start writing a connection pool.

app/src/Infrastructure/Api/Database/ConnectionPoolInterface.php

@@ -2,11 +2,40 @@
 
 namespace Slovocast\Infrastructure\Api\Database;
 
+use Exception;
+
 interface ConnectionPoolInterface
 {
-    public function getFreeConnectionsCount(): int;
-    public function getActiveConnectionsCount(): int;
-    public function hasFreeConnection(): bool;
-    public function getConnection(): ConnectionInterface;
-    public function releaseConnection(ConnectionInterface $connection): void;
+    public function getTotalIdleConnections(): int;
+    public function getTotalActiveConnections(): int;
+
+    /**
+     * If there is at least one idle connection waiting to be used.
+     *
+     * @return bool
+     */
+    public function hasIdleConnection(): bool;
+    public function setWaitTimeout(int $seconds): void;
+    public function getWaitTimeout(): int;
+    public function getConnectionLimit(): int;
+
+    /**
+     * This method will grab a connection from the Idle list, push it into the Active list and returns that same
+     * connection to the caller. If there is no active connections, the method will wait based on the `waitTimeout`
+     * value (in seconds) and throw an exception when the timeout has been reached.
+     *
+     * @throws Exception When the Wait Timeout is surpassed waiting for an idle connection
+     * @return PooledConnectionInterface
+     */
+    public function getConnection(): PooledConnectionInterface;
+
+    /**
+     * This method will return a connection from the Active list into the Idle list.
+     *
+     * @param PooledConnectionInterface $connection
+     * @return void
+     */
+    public function releaseConnection(PooledConnectionInterface $connection): void;
+
+
 }

app/src/Infrastructure/Database/ConnectionPool.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace Slovocast\Infrastructure\Database;
+
+use Slovocast\Infrastructure\Api\Database\ConnectionPoolInterface;
+use Slovocast\Infrastructure\Api\Database\PooledConnectionInterface;
+
+class ConnectionPool implements ConnectionPoolInterface
+{
+    /**
+     * Set a default wait timeout for acquiring a connection to 100ms
+     */
+    const int DEFAULT_WAIT_TIMEOUT = 100;
+    private array $idleConnections;
+    private array $activeConnections;
+
+    public function getTotalIdleConnections(): int
+    {
+        // TODO: Implement getTotalIdleConnections() method.
+    }
+
+    public function getTotalActiveConnections(): int
+    {
+        // TODO: Implement getTotalActiveConnections() method.
+    }
+
+    public function hasIdleConnection(): bool
+    {
+        // TODO: Implement hasIdleConnection() method.
+    }
+
+    public function setWaitTimeout(int $seconds): void
+    {
+        // TODO: Implement setWaitTimeout() method.
+    }
+
+    public function getWaitTimeout(): int
+    {
+        // TODO: Implement getWaitTimeout() method.
+    }
+
+    public function getConnectionLimit(): int
+    {
+        // TODO: Implement getConnectionLimit() method.
+    }
+
+    public function getConnection(): PooledConnectionInterface
+    {
+        // TODO: Implement getConnection() method.
+    }
+
+    public function releaseConnection(PooledConnectionInterface $connection): void
+    {
+        // TODO: Implement releaseConnection() method.
+    }
+}

app/src/Infrastructure/Database/ConnectionPoolConfig.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Slovocast\Infrastructure\Database;
+
+class ConnectionPoolConfig
+{
+    public function __construct(
+        public readonly string $username,
+        public readonly string $password,
+        public readonly string $database,
+        protected int $port = 3306,
+        protected int $poolWaitTimeout = ConnectionPool::DEFAULT_WAIT_TIMEOUT,
+    ) { }
+
+    public function getPort(): int
+    {
+        return $this->port;
+    }
+
+    public function getPoolWaitTimeout(): int
+    {
+        return $this->poolWaitTimeout;
+    }
+}