Implement "idle" timeout to close underlying connection when unused

Author: clue

README.md

@@ -173,9 +173,9 @@ This method immediately returns a "virtual" connection implementing the
 interface with your MySQL database. Internally, it lazily creates the
 underlying database connection only on demand once the first request is
 invoked on this instance and will queue all outstanding requests until
-the underlying connection is ready. Additionally, it will keep track of
-this underlying connection and will create a new underlying connection
-on demand when the current connection is lost.
+the underlying connection is ready. Additionally, it will only keep this
+underlying connection in an "idle" state for 60s by default and will
+automatically end the underlying connection when it is no longer needed.
 
 From a consumer side this means that you can start sending queries to the
 database right away while the underlying connection may still be
@@ -189,15 +189,17 @@ having to deal with its async resolution.
 If the underlying database connection fails, it will reject all
 outstanding commands and will return to the initial "idle" state. This
 means that you can keep sending additional commands at a later time which
-will again try to open the underlying connection.
+will again try to open a new underlying connection. Note that this may
+require special care if you're using transactions that are kept open for
+longer than the idle period.
 
 Note that creating the underlying connection will be deferred until the
 first request is invoked. Accordingly, any eventual connection issues
 will be detected once this instance is first used. You can use the
 `quit()` method to ensure that the "virtual" connection will be soft-closed
 and no further commands can be enqueued. Similarly, calling `quit()` on
-this instance before invoking any requests will succeed immediately and
-will not wait for an actual underlying connection.
+this instance when not currently connected will succeed immediately and
+will not have to wait for an actual underlying connection.
 
 Depending on your particular use case, you may prefer this method or the
 underlying `createConnection()` which resolves with a promise. For many
@@ -234,6 +236,19 @@ in seconds (or use a negative number to not apply a timeout) like this:
 $factory->createLazyConnection('localhost?timeout=0.5');
 ```
 
+By default, this method will keep "idle" connection open for 60s and will
+then end the underlying connection. The next request after an "idle"
+connection ended will automatically create a new underlying connection.
+This ensure you always get a "fresh" connection and as such should not be
+confused with a "keepalive" or "heartbeat" mechanism, as this will not
+actively try to probe the connection. You can explicitly pass a custom
+idle timeout value in seconds (or use a negative number to not apply a
+timeout) like this:
+
+```php
+$factory->createLazyConnection('localhost?idle=0.1');
+```
+
 ### ConnectionInterface
 
 The `ConnectionInterface` represents a connection that is responsible for
@@ -435,7 +450,7 @@ $connecion->on('close', function () {
 });
 ```
 
-See also the [#close](#close) method.
+See also the [`close()`](#close) method.
 
 ## Install
 

composer.json

@@ -6,7 +6,7 @@
     "require": {
         "php": ">=5.4.0",
         "evenement/evenement": "^3.0 || ^2.1 || ^1.1",
-        "react/event-loop": "^1.0 || ^0.5 || ^0.4",
+        "react/event-loop": "^1.0 || ^0.5",
         "react/promise": "^2.7",
         "react/promise-stream": "^1.1",
         "react/promise-timer": "^1.5",

src/ConnectionInterface.php

@@ -38,7 +38,7 @@
  *     });
  *     ```
  *
- *     See also the [#close](#close) method.
+ *     See also the [`close()`](#close) method.
  */
 interface ConnectionInterface extends EventEmitterInterface
 {

src/Factory.php

@@ -213,9 +213,9 @@ public function createConnection($uri)
      * interface with your MySQL database. Internally, it lazily creates the
      * underlying database connection only on demand once the first request is
      * invoked on this instance and will queue all outstanding requests until
-     * the underlying connection is ready. Additionally, it will keep track of
-     * this underlying connection and will create a new underlying connection
-     * on demand when the current connection is lost.
+     * the underlying connection is ready. Additionally, it will only keep this
+     * underlying connection in an "idle" state for 60s by default and will
+     * automatically end the underlying connection when it is no longer needed.
      *
      * From a consumer side this means that you can start sending queries to the
      * database right away while the underlying connection may still be
@@ -229,15 +229,17 @@ public function createConnection($uri)
      * If the underlying database connection fails, it will reject all
      * outstanding commands and will return to the initial "idle" state. This
      * means that you can keep sending additional commands at a later time which
-     * will again try to open the underlying connection.
+     * will again try to open a new underlying connection. Note that this may
+     * require special care if you're using transactions that are kept open for
+     * longer than the idle period.
      *
      * Note that creating the underlying connection will be deferred until the
      * first request is invoked. Accordingly, any eventual connection issues
      * will be detected once this instance is first used. You can use the
      * `quit()` method to ensure that the "virtual" connection will be soft-closed
      * and no further commands can be enqueued. Similarly, calling `quit()` on
-     * this instance before invoking any requests will succeed immediately and
-     * will not wait for an actual underlying connection.
+     * this instance when not currently connected will succeed immediately and
+     * will not have to wait for an actual underlying connection.
      *
      * Depending on your particular use case, you may prefer this method or the
      * underlying `createConnection()` which resolves with a promise. For many
@@ -274,11 +276,24 @@ public function createConnection($uri)
      * $factory->createLazyConnection('localhost?timeout=0.5');
      * ```
      *
+     * By default, this method will keep "idle" connection open for 60s and will
+     * then end the underlying connection. The next request after an "idle"
+     * connection ended will automatically create a new underlying connection.
+     * This ensure you always get a "fresh" connection and as such should not be
+     * confused with a "keepalive" or "heartbeat" mechanism, as this will not
+     * actively try to probe the connection. You can explicitly pass a custom
+     * idle timeout value in seconds (or use a negative number to not apply a
+     * timeout) like this:
+     *
+     * ```php
+     * $factory->createLazyConnection('localhost?idle=0.1');
+     * ```
+     *
      * @param string $uri
      * @return ConnectionInterface
      */
     public function createLazyConnection($uri)
     {
-        return new LazyConnection($this, $uri);
+        return new LazyConnection($this, $uri, $this->loop);
     }
 }

src/Io/LazyConnection.php

@@ -6,6 +6,8 @@
 use Evenement\EventEmitter;
 use React\MySQL\Exception;
 use React\MySQL\Factory;
+use React\EventLoop\LoopInterface;
+use React\MySQL\QueryResult;
 
 /**
  * @internal
@@ -19,10 +21,22 @@ class LazyConnection extends EventEmitter implements ConnectionInterface
     private $closed = false;
     private $busy = false;
 
-    public function __construct(Factory $factory, $uri)
+    private $loop;
+    private $idlePeriod = 60.0;
+    private $idleTimer;
+    private $pending = 0;
+
+    public function __construct(Factory $factory, $uri, LoopInterface $loop)
     {
+        $args = array();
+        \parse_str(\parse_url($uri, \PHP_URL_QUERY), $args);
+        if (isset($args['idle'])) {
+            $this->idlePeriod = (float)$args['idle'];
+        }
+
         $this->factory = $factory;
         $this->uri = $uri;
+        $this->loop = $loop;
     }
 
     private function connecting()
@@ -36,6 +50,11 @@ private function connecting()
             // connection completed => remember only until closed
             $connection->on('close', function () {
                 $this->connecting = null;
+
+                if ($this->idleTimer !== null) {
+                    $this->loop->cancelTimer($this->idleTimer);
+                    $this->idleTimer = null;
+                }
             });
         }, function () {
             // connection failed => discard connection attempt
@@ -45,14 +64,49 @@ private function connecting()
         return $connecting;
     }
 
+    private function awake()
+    {
+        ++$this->pending;
+
+        if ($this->idleTimer !== null) {
+            $this->loop->cancelTimer($this->idleTimer);
+            $this->idleTimer = null;
+        }
+    }
+
+    private function idle()
+    {
+        --$this->pending;
+
+        if ($this->pending < 1 && $this->idlePeriod >= 0) {
+            $this->idleTimer = $this->loop->addTimer($this->idlePeriod, function () {
+                $this->connecting->then(function (ConnectionInterface $connection) {
+                    $connection->quit();
+                });
+                $this->connecting = null;
+                $this->idleTimer = null;
+            });
+        }
+    }
+
     public function query($sql, array $params = [])
     {
         if ($this->closed) {
             return \React\Promise\reject(new Exception('Connection closed'));
         }
 
         return $this->connecting()->then(function (ConnectionInterface $connection) use ($sql, $params) {
-            return $connection->query($sql, $params);
+            $this->awake();
+            return $connection->query($sql, $params)->then(
+                function (QueryResult $result) {
+                    $this->idle();
+                    return $result;
+                },
+                function (\Exception $e) {
+                    $this->idle();
+                    throw $e;
+                }
+            );
         });
     }
 
@@ -64,7 +118,14 @@ public function queryStream($sql, $params = [])
 
         return \React\Promise\Stream\unwrapReadable(
             $this->connecting()->then(function (ConnectionInterface $connection) use ($sql, $params) {
-                return $connection->queryStream($sql, $params);
+                $stream = $connection->queryStream($sql, $params);
+
+                $this->awake();
+                $stream->on('close', function () {
+                    $this->idle();
+                });
+
+                return $stream;
             })
         );
     }
@@ -76,7 +137,16 @@ public function ping()
         }
 
         return $this->connecting()->then(function (ConnectionInterface $connection) {
-            return $connection->ping();
+            $this->awake();
+            return $connection->ping()->then(
+                function () {
+                    $this->idle();
+                },
+                function (\Exception $e) {
+                    $this->idle();
+                    throw $e;
+                }
+            );
         });
     }
 
@@ -93,6 +163,7 @@ public function quit()
         }
 
         return $this->connecting()->then(function (ConnectionInterface $connection) {
+            $this->awake();
             return $connection->quit()->then(
                 function () {
                     $this->close();
@@ -122,6 +193,11 @@ public function close()
             $this->connecting = null;
         }
 
+        if ($this->idleTimer !== null) {
+            $this->loop->cancelTimer($this->idleTimer);
+            $this->idleTimer = null;
+        }
+
         $this->emit('close');
         $this->removeAllListeners();
     }

tests/FactoryTest.php

@@ -387,6 +387,19 @@ public function testConnectLazyWithValidAuthWillRunUntilQuitAfterPing()
         $loop->run();
     }
 
+    public function testConnectLazyWithValidAuthWillRunUntilIdleTimerAfterPingEvenWithoutQuit()
+    {
+        $loop = \React\EventLoop\Factory::create();
+        $factory = new Factory($loop);
+
+        $uri = $this->getConnectionString() . '?idle=0';
+        $connection = $factory->createLazyConnection($uri);
+
+        $connection->ping();
+
+        $loop->run();
+    }
+
     public function testConnectLazyWithInvalidAuthWillRejectPingButWillNotEmitErrorOrClose()
     {
         $loop = \React\EventLoop\Factory::create();