From 4a66af0f2beee33d6a4271cf21733a76c545ffb6 Mon Sep 17 00:00:00 2001
From: Dave Smith-Hayes <me@davesmithhayes.com>
Date: Mon, 23 Sep 2024 19:41:50 -0400
Subject: [PATCH] Document the connection pool interface a bit, start writing a
 connection pool.

---
 .../Api/Database/ConnectionPoolInterface.php  | 39 +++++++++++--
 ...face.php => PooledConnectionInterface.php} |  0
 .../Database/ConnectionPool.php               | 56 +++++++++++++++++++
 .../Database/ConnectionPoolConfig.php         | 24 ++++++++
 4 files changed, 114 insertions(+), 5 deletions(-)
 rename app/src/Infrastructure/Api/Database/{ConnectionInterface.php => PooledConnectionInterface.php} (100%)
 create mode 100644 app/src/Infrastructure/Database/ConnectionPool.php
 create mode 100644 app/src/Infrastructure/Database/ConnectionPoolConfig.php

diff --git a/app/src/Infrastructure/Api/Database/ConnectionPoolInterface.php b/app/src/Infrastructure/Api/Database/ConnectionPoolInterface.php
index 18754e7..4b614d8 100644
--- a/app/src/Infrastructure/Api/Database/ConnectionPoolInterface.php
+++ b/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;
+
+
 }
diff --git a/app/src/Infrastructure/Api/Database/ConnectionInterface.php b/app/src/Infrastructure/Api/Database/PooledConnectionInterface.php
similarity index 100%
rename from app/src/Infrastructure/Api/Database/ConnectionInterface.php
rename to app/src/Infrastructure/Api/Database/PooledConnectionInterface.php
diff --git a/app/src/Infrastructure/Database/ConnectionPool.php b/app/src/Infrastructure/Database/ConnectionPool.php
new file mode 100644
index 0000000..534343f
--- /dev/null
+++ b/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.
+    }
+}
diff --git a/app/src/Infrastructure/Database/ConnectionPoolConfig.php b/app/src/Infrastructure/Database/ConnectionPoolConfig.php
new file mode 100644
index 0000000..8f15943
--- /dev/null
+++ b/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;
+    }
+}