PHPLIB-451: Internal TailableCursorIterator class

This can be used to ensure rewinding is a NOP (i.e. getMore will not be executed) for tailable cursors with an empty firstBatch.

src/Model/TailableCursorIterator.php

+<?php
+/*
+ * Copyright 2019 MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+namespace MongoDB\Model;
+
+use MongoDB\Driver\Cursor;
+use IteratorIterator;
+
+/**
+ * Iterator for tailable cursors.
+ *
+ * This iterator may be used to wrap a tailable cursor. By indicating whether
+ * the cursor's first batch of results is empty, this iterator can NOP initial
+ * calls to rewind() and prevent it from executing a getMore command.
+ *
+ * @internal
+ */
+class TailableCursorIterator extends IteratorIterator
+{
+    private $isRewindNop;
+
+    /**
+     * Constructor.
+     *
+     * @internal
+     * @param Cursor  $cursor
+     * @param boolean $isFirstBatchIsEmpty
+     */
+    public function __construct(Cursor $cursor, $isFirstBatchIsEmpty)
+    {
+        parent::__construct($cursor);
+        $this->isRewindNop = $isFirstBatchIsEmpty;
+    }
+
+    /**
+     * @see https://php.net/iteratoriterator.rewind
+     * @return void
+     */
+    public function next()
+    {
+        try {
+            parent::next();
+        } finally {
+            /* If the cursor ever advances to a valid position, do not prevent
+             * future attempts to rewind the cursor. This will allow the driver
+             * to throw a LogicException if the cursor has been advanced past
+             * its first element. */
+            if ($this->valid()) {
+                $this->isRewindNop = false;
+            }
+        }
+    }
+
+    /**
+     * @see https://php.net/iteratoriterator.rewind
+     * @return void
+     */
+    public function rewind()
+    {
+        if ($this->isRewindNop) {
+            return;
+        }
+
+        parent::rewind();
+    }
+}

tests/Model/TailableCursorIteratorTest.php

+<?php
+
+namespace MongoDB\Tests\Model;
+
+use MongoDB\Collection;
+use MongoDB\Driver\Exception\LogicException;
+use MongoDB\Model\TailableCursorIterator;
+use MongoDB\Operation\Find;
+use MongoDB\Operation\CreateCollection;
+use MongoDB\Operation\DropCollection;
+use MongoDB\Tests\CommandObserver;
+use MongoDB\Tests\FunctionalTestCase;
+
+class TailableCursorIteratorTest extends FunctionalTestCase
+{
+    private $collection;
+
+    public function setUp()
+    {
+        parent::setUp();
+
+        $operation = new DropCollection($this->getDatabaseName(), $this->getCollectionName());
+        $operation->execute($this->getPrimaryServer());
+
+        $operation = new CreateCollection($this->getDatabaseName(), $this->getCollectionName(), ['capped' => true, 'size' => 8192]);
+        $operation->execute($this->getPrimaryServer());
+
+        $this->collection = new Collection($this->manager, $this->getDatabaseName(), $this->getCollectionName());
+    }
+
+    public function testFirstBatchIsEmpty()
+    {
+        $this->collection->insertOne(['x' => 1]);
+
+        $cursor = $this->collection->find(['x' => ['$gt' => 1]], ['cursorType' => Find::TAILABLE]);
+        $iterator = new TailableCursorIterator($cursor, true);
+
+        $this->assertNoCommandExecuted(function() use ($iterator) { $iterator->rewind(); });
+        $this->assertFalse($iterator->valid());
+
+        $this->collection->insertOne(['x' => 2]);
+
+        $iterator->next();
+        $this->assertTrue($iterator->valid());
+        $this->assertMatchesDocument(['x' => 2], $iterator->current());
+
+        $this->expectException(LogicException::class);
+        $iterator->rewind();
+    }
+
+    public function testFirstBatchIsNotEmpty()
+    {
+        $this->collection->insertOne(['x' => 1]);
+
+        $cursor = $this->collection->find([], ['cursorType' => Find::TAILABLE]);
+        $iterator = new TailableCursorIterator($cursor, false);
+
+        $this->assertNoCommandExecuted(function() use ($iterator) { $iterator->rewind(); });
+        $this->assertTrue($iterator->valid());
+        $this->assertMatchesDocument(['x' => 1], $iterator->current());
+
+        $this->collection->insertOne(['x' => 2]);
+
+        $iterator->next();
+        $this->assertTrue($iterator->valid());
+        $this->assertMatchesDocument(['x' => 2], $iterator->current());
+
+        $this->expectException(LogicException::class);
+        $iterator->rewind();
+    }
+
+    private function assertNoCommandExecuted(callable $callable)
+    {
+        $commands = [];
+
+        (new CommandObserver)->observe(
+            $callable,
+            function(array $event) use (&$commands) {
+                $this->fail(sprintf('"%s" command was executed', $event['started']->getCommandName()));
+            }
+        );
+
+        $this->assertEmpty($commands);
+    }
+}