Create lazy connection only on demand (on first command)

clue · clue · commit 83ac29b4bf8f · 2018-10-18T16:41:33.000+02:00
diff --git a/README.md b/README.md
@@ -171,18 +171,25 @@ $connection->query(…);
 This method immediately returns a "virtual" connection implementing the
 [`ConnectionInterface`](#connectioninterface) that can be used to
 interface with your MySQL database. Internally, it lazily creates the
-underlying database connection (which may take some time) and will
-queue all outstanding requests until the underlying connection is ready.
+underlying database connection (which may take some time) only once the
+first request is invoked on this instance and will queue all outstanding
+requests until the underlying connection is ready.
 
 From a consumer side this means that you can start sending queries to the
-database right away while the connection may still be pending. It will
-ensure that all commands will be executed in the order they are enqueued
-once the connection is ready. If the database connection fails, it will
-emit an `error` event, reject all outstanding commands and `close` the
-connection as described in the `ConnectionInterface`. In other words, it
-behaves just like a real connection and frees you from having to deal
+database right away while the actual connection may still be outstanding.
+It will ensure that all commands will be executed in the order they are
+enqueued once the connection is ready. If the database connection fails,
+it will emit an `error` event, reject all outstanding commands and `close`
+the connection as described in the `ConnectionInterface`. In other words,
+it behaves just like a real connection and frees you from having to deal
 with its async resolution.
 
+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. Similarly, calling
+`quit()` on this instance before invoking any requests will succeed
+immediately and will not 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
 simple use cases it may be easier to create a lazy connection.
@@ -210,9 +217,9 @@ $factory->createLazyConnection('localhost');
 ```
 
 This method respects PHP's `default_socket_timeout` setting (default 60s)
-as a timeout for establishing the connection and waiting for successful
-authentication. You can explicitly pass a custom timeout value in seconds
-(or use a negative number to not apply a timeout) like this:
+as a timeout for establishing the underlying connection and waiting for
+successful authentication. You can explicitly pass a custom timeout value
+in seconds (or use a negative number to not apply a timeout) like this:
 
 ```php
 $factory->createLazyConnection('localhost?timeout=0.5');
diff --git a/src/Factory.php b/src/Factory.php
@@ -211,18 +211,25 @@ public function createConnection($uri)
      * This method immediately returns a "virtual" connection implementing the
      * [`ConnectionInterface`](#connectioninterface) that can be used to
      * interface with your MySQL database. Internally, it lazily creates the
-     * underlying database connection (which may take some time) and will
-     * queue all outstanding requests until the underlying connection is ready.
+     * underlying database connection (which may take some time) only once the
+     * first request is invoked on this instance and will queue all outstanding
+     * requests until the underlying connection is ready.
      *
      * From a consumer side this means that you can start sending queries to the
-     * database right away while the connection may still be pending. It will
-     * ensure that all commands will be executed in the order they are enqueued
-     * once the connection is ready. If the database connection fails, it will
-     * emit an `error` event, reject all outstanding commands and `close` the
-     * connection as described in the `ConnectionInterface`. In other words, it
-     * behaves just like a real connection and frees you from having to deal
+     * database right away while the actual connection may still be outstanding.
+     * It will ensure that all commands will be executed in the order they are
+     * enqueued once the connection is ready. If the database connection fails,
+     * it will emit an `error` event, reject all outstanding commands and `close`
+     * the connection as described in the `ConnectionInterface`. In other words,
+     * it behaves just like a real connection and frees you from having to deal
      * with its async resolution.
      *
+     * 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. Similarly, calling
+     * `quit()` on this instance before invoking any requests will succeed
+     * immediately and will not 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
      * simple use cases it may be easier to create a lazy connection.
@@ -250,9 +257,9 @@ public function createConnection($uri)
      * ```
      *
      * This method respects PHP's `default_socket_timeout` setting (default 60s)
-     * as a timeout for establishing the connection and waiting for successful
-     * authentication. You can explicitly pass a custom timeout value in seconds
-     * (or use a negative number to not apply a timeout) like this:
+     * as a timeout for establishing the underlying connection and waiting for
+     * successful authentication. You can explicitly pass a custom timeout value
+     * in seconds (or use a negative number to not apply a timeout) like this:
      *
      * ```php
      * $factory->createLazyConnection('localhost?timeout=0.5');
@@ -263,6 +270,6 @@ public function createConnection($uri)
      */
     public function createLazyConnection($uri)
     {
-        return new LazyConnection($this->createConnection($uri));
+        return new LazyConnection($this, $uri);
     }
 }
diff --git a/src/Io/LazyConnection.php b/src/Io/LazyConnection.php
@@ -4,84 +4,102 @@
 
 use React\MySQL\ConnectionInterface;
 use Evenement\EventEmitter;
-use React\Promise\PromiseInterface;
 use React\MySQL\Exception;
+use React\MySQL\Factory;
 
 /**
  * @internal
  * @see \React\MySQL\Factory::createLazyConnection()
  */
 class LazyConnection extends EventEmitter implements ConnectionInterface
 {
+    private $factory;
+    private $uri;
     private $connecting;
     private $closed = false;
     private $busy = false;
 
-    public function __construct(PromiseInterface $connecting)
+    public function __construct(Factory $factory, $uri)
     {
-        $this->connecting = $connecting;
+        $this->factory = $factory;
+        $this->uri = $uri;
+    }
+
+    private function connecting()
+    {
+        if ($this->connecting === null) {
+            $this->connecting = $this->factory->createConnection($this->uri);
+
+            $this->connecting->then(function (ConnectionInterface $connection) {
+                // connection completed => forward error and close events
+                $connection->on('error', function ($e) {
+                    $this->emit('error', [$e]);
+                });
+                $connection->on('close', function () {
+                    $this->close();
+                });
+            }, function (\Exception $e) {
+                // connection failed => emit error if connection is not already closed
+                if ($this->closed) {
+                    return;
+                }
 
-        $connecting->then(function (ConnectionInterface $connection) {
-            // connection completed => forward error and close events
-            $connection->on('error', function ($e) {
                 $this->emit('error', [$e]);
-            });
-            $connection->on('close', function () {
                 $this->close();
             });
-        }, function (\Exception $e) {
-            // connection failed => emit error if connection is not already closed
-            if ($this->closed) {
-                return;
-            }
+        }
 
-            $this->emit('error', [$e]);
-            $this->close();
-        });
+        return $this->connecting;
     }
 
     public function query($sql, array $params = [])
     {
-        if ($this->connecting === null) {
+        if ($this->closed) {
             return \React\Promise\reject(new Exception('Connection closed'));
         }
 
-        return $this->connecting->then(function (ConnectionInterface $connection) use ($sql, $params) {
+        return $this->connecting()->then(function (ConnectionInterface $connection) use ($sql, $params) {
             return $connection->query($sql, $params);
         });
     }
 
     public function queryStream($sql, $params = [])
     {
-        if ($this->connecting === null) {
+        if ($this->closed) {
             throw new Exception('Connection closed');
         }
 
         return \React\Promise\Stream\unwrapReadable(
-            $this->connecting->then(function (ConnectionInterface $connection) use ($sql, $params) {
+            $this->connecting()->then(function (ConnectionInterface $connection) use ($sql, $params) {
                 return $connection->queryStream($sql, $params);
             })
         );
     }
 
     public function ping()
     {
-        if ($this->connecting === null) {
+        if ($this->closed) {
             return \React\Promise\reject(new Exception('Connection closed'));
         }
 
-        return $this->connecting->then(function (ConnectionInterface $connection) {
+        return $this->connecting()->then(function (ConnectionInterface $connection) {
             return $connection->ping();
         });
     }
 
     public function quit()
     {
-        if ($this->connecting === null) {
+        if ($this->closed) {
             return \React\Promise\reject(new Exception('Connection closed'));
         }
 
-        return $this->connecting->then(function (ConnectionInterface $connection) {
+        // not already connecting => no need to connect, simply close virtual connection
+        if ($this->connecting === null) {
+            $this->close();
+            return \React\Promise\resolve();
+        }
+
+        return $this->connecting()->then(function (ConnectionInterface $connection) {
             return $connection->quit();
         });
     }
@@ -95,12 +113,13 @@ public function close()
         $this->closed = true;
 
         // either close active connection or cancel pending connection attempt
-        $this->connecting->then(function (ConnectionInterface $connection) {
-            $connection->close();
-        });
-        $this->connecting->cancel();
-
-        $this->connecting = null;
+        if ($this->connecting !== null) {
+            $this->connecting->then(function (ConnectionInterface $connection) {
+                $connection->close();
+            });
+            $this->connecting->cancel();
+            $this->connecting = null;
+        }
 
         $this->emit('close');
         $this->removeAllListeners();
diff --git a/tests/FactoryTest.php b/tests/FactoryTest.php
@@ -353,7 +353,22 @@ public function testCancelConnectDuringAuthenticationWillCloseConnection()
         })));
     }
 
-    public function testConnectLazyWithValidAuthWillRunUntilQuit()
+    public function testConnectLazyWithAnyAuthWillQuitWithoutRunning()
+    {
+        $this->expectOutputString('closed.');
+
+        $loop = \React\EventLoop\Factory::create();
+        $factory = new Factory($loop);
+
+        $uri = 'mysql://random:pass@host';
+        $connection = $factory->createLazyConnection($uri);
+
+        $connection->quit()->then(function () {
+            echo 'closed.';
+        });
+    }
+
+    public function testConnectLazyWithValidAuthWillRunUntilQuitAfterPing()
     {
         $this->expectOutputString('closed.');
 
@@ -363,14 +378,16 @@ public function testConnectLazyWithValidAuthWillRunUntilQuit()
         $uri = $this->getConnectionString();
         $connection = $factory->createLazyConnection($uri);
 
+        $connection->ping();
+
         $connection->quit()->then(function () {
             echo 'closed.';
         });
 
         $loop->run();
     }
 
-    public function testConnectLazyWithInvalidAuthWillEmitErrorAndClose()
+    public function testConnectLazyWithInvalidAuthWillEmitErrorAndCloseAfterPing()
     {
         $loop = \React\EventLoop\Factory::create();
         $factory = new Factory($loop);
@@ -381,6 +398,8 @@ public function testConnectLazyWithInvalidAuthWillEmitErrorAndClose()
         $connection->on('error', $this->expectCallableOnce());
         $connection->on('close', $this->expectCallableOnce());
 
+        $connection->ping();
+
         $loop->run();
     }
 
diff --git a/tests/Io/LazyConnectionTest.php b/tests/Io/LazyConnectionTest.php
