PHPLIB-712: Allow hint for unacknowledged writes using OP_MSG when supported by the server

src/Operation/Delete.php

@@ -29,6 +29,7 @@
 use function is_array;
 use function is_object;
 use function is_string;
+use function MongoDB\is_write_concern_acknowledged;
 use function MongoDB\server_supports_feature;
 
 /**
@@ -45,8 +46,11 @@ class Delete implements Executable, Explainable
     /** @var integer */
     private static $wireVersionForCollation = 5;
 
+    /** @var integer */
+    private static $wireVersionForHint = 9;
+
     /** @var int */
-    private static $wireVersionForHintServerSideError = 5;
+    private static $wireVersionForUnsupportedOptionServerSideError = 5;
 
     /** @var string */
     private $databaseName;
@@ -146,10 +150,18 @@ public function execute(Server $server)
             throw UnsupportedException::collationNotSupported();
         }
 
-        /* Server versions >= 3.4.0 raise errors for unknown update
-         * options. For previous versions, the CRUD spec requires a client-side
-         * error. */
-        if (isset($this->options['hint']) && ! server_supports_feature($server, self::$wireVersionForHintServerSideError)) {
+        /* Server versions >= 3.4.0 raise errors for unsupported update options.
+         * For previous versions, the CRUD spec requires a client-side error. */
+        if (isset($this->options['hint']) && ! server_supports_feature($server, self::$wireVersionForUnsupportedOptionServerSideError)) {
+            throw UnsupportedException::hintNotSupported();
+        }
+
+        /* CRUD spec requires a client-side error when using "hint" with an
+         * unacknowledged write concern on an unsupported server. */
+        if (
+            isset($this->options['writeConcern']) && ! is_write_concern_acknowledged($this->options['writeConcern']) &&
+            isset($this->options['hint']) && ! server_supports_feature($server, self::$wireVersionForHint)
+        ) {
             throw UnsupportedException::hintNotSupported();
         }
 

src/Operation/FindAndModify.php

@@ -34,6 +34,7 @@
 use function is_string;
 use function MongoDB\create_field_path_type_map;
 use function MongoDB\is_pipeline;
+use function MongoDB\is_write_concern_acknowledged;
 use function MongoDB\server_supports_feature;
 
 /**
@@ -60,7 +61,7 @@ class FindAndModify implements Executable, Explainable
     private static $wireVersionForHint = 9;
 
     /** @var integer */
-    private static $wireVersionForHintServerSideError = 8;
+    private static $wireVersionForUnsupportedOptionServerSideError = 8;
 
     /** @var integer */
     private static $wireVersionForWriteConcern = 4;
@@ -245,11 +246,18 @@ public function execute(Server $server)
             throw UnsupportedException::collationNotSupported();
         }
 
-        /* Server versions >= 4.1.10 raise errors for unknown findAndModify
-         * options (SERVER-40005), but the CRUD spec requires client-side errors
-         * for server versions < 4.2. For later versions, we'll rely on the
-         * server to either utilize the option or report its own error. */
-        if (isset($this->options['hint']) && ! $this->isHintSupported($server)) {
+        /* Server versions >= 4.2.0 raise errors for unsupported update options.
+         * For previous versions, the CRUD spec requires a client-side error. */
+        if (isset($this->options['hint']) && ! server_supports_feature($server, self::$wireVersionForUnsupportedOptionServerSideError)) {
+            throw UnsupportedException::hintNotSupported();
+        }
+
+        /* CRUD spec requires a client-side error when using "hint" with an
+         * unacknowledged write concern on an unsupported server. */
+        if (
+            isset($this->options['writeConcern']) && ! is_write_concern_acknowledged($this->options['writeConcern']) &&
+            isset($this->options['hint']) && ! server_supports_feature($server, self::$wireVersionForHint)
+        ) {
             throw UnsupportedException::hintNotSupported();
         }
 
@@ -350,20 +358,4 @@ private function createOptions()
 
         return $options;
     }
-
-    private function isAcknowledgedWriteConcern(): bool
-    {
-        if (! isset($this->options['writeConcern'])) {
-            return true;
-        }
-
-        return $this->options['writeConcern']->getW() > 1 || $this->options['writeConcern']->getJournal();
-    }
-
-    private function isHintSupported(Server $server): bool
-    {
-        $requiredWireVersion = $this->isAcknowledgedWriteConcern() ? self::$wireVersionForHintServerSideError : self::$wireVersionForHint;
-
-        return server_supports_feature($server, $requiredWireVersion);
-    }
 }

src/Operation/Update.php

@@ -32,6 +32,7 @@
 use function is_string;
 use function MongoDB\is_first_key_operator;
 use function MongoDB\is_pipeline;
+use function MongoDB\is_write_concern_acknowledged;
 use function MongoDB\server_supports_feature;
 
 /**
@@ -55,7 +56,10 @@ class Update implements Executable, Explainable
     private static $wireVersionForDocumentLevelValidation = 4;
 
     /** @var integer */
-    private static $wireVersionForHintServerSideError = 5;
+    private static $wireVersionForHint = 8;
+
+    /** @var integer */
+    private static $wireVersionForUnsupportedOptionServerSideError = 5;
 
     /** @var string */
     private $databaseName;
@@ -203,10 +207,18 @@ public function execute(Server $server)
             throw UnsupportedException::collationNotSupported();
         }
 
-        /* Server versions >= 3.4.0 raise errors for unknown update
-         * options. For previous versions, the CRUD spec requires a client-side
-         * error. */
-        if (isset($this->options['hint']) && ! server_supports_feature($server, self::$wireVersionForHintServerSideError)) {
+        /* Server versions >= 3.4.0 raise errors for unsupported update options.
+         * For previous versions, the CRUD spec requires a client-side error. */
+        if (isset($this->options['hint']) && ! server_supports_feature($server, self::$wireVersionForUnsupportedOptionServerSideError)) {
+            throw UnsupportedException::hintNotSupported();
+        }
+
+        /* CRUD spec requires a client-side error when using "hint" with an
+         * unacknowledged write concern on an unsupported server. */
+        if (
+            isset($this->options['writeConcern']) && ! is_write_concern_acknowledged($this->options['writeConcern']) &&
+            isset($this->options['hint']) && ! server_supports_feature($server, self::$wireVersionForHint)
+        ) {
             throw UnsupportedException::hintNotSupported();
         }
 

src/functions.php

@@ -23,6 +23,7 @@
 use MongoDB\Driver\ReadPreference;
 use MongoDB\Driver\Server;
 use MongoDB\Driver\Session;
+use MongoDB\Driver\WriteConcern;
 use MongoDB\Exception\InvalidArgumentException;
 use MongoDB\Exception\RuntimeException;
 use MongoDB\Operation\WithTransaction;
@@ -239,6 +240,25 @@ function is_mapreduce_output_inline($out): bool
     return key($out) === 'inline';
 }
 
+/**
+ * Return whether the write concern is acknowledged.
+ *
+ * This function is similar to mongoc_write_concern_is_acknowledged but does not
+ * check the fsync option since that was never supported in the PHP driver.
+ *
+ * @internal
+ * @see https://docs.mongodb.com/manual/reference/write-concern/
+ * @param WriteConcern $writeConcern
+ * @return boolean
+ */
+function is_write_concern_acknowledged(WriteConcern $writeConcern): bool
+{
+    /* Note: -1 corresponds to MONGOC_WRITE_CONCERN_W_ERRORS_IGNORED, which is
+     * deprecated synonym of MONGOC_WRITE_CONCERN_W_UNACKNOWLEDGED and slated
+     * for removal in libmongoc 2.0. */
+    return ($writeConcern->getW() !== 0 && $writeConcern->getW() !== -1) || $writeConcern->getJournal() === true;
+}
+
 /**
  * Return whether the server supports a particular feature.
  *

tests/FunctionsTest.php

@@ -2,6 +2,7 @@
 
 namespace MongoDB\Tests;
 
+use MongoDB\Driver\WriteConcern;
 use MongoDB\Exception\InvalidArgumentException;
 use MongoDB\Model\BSONArray;
 use MongoDB\Model\BSONDocument;
@@ -12,6 +13,7 @@
 use function MongoDB\is_first_key_operator;
 use function MongoDB\is_mapreduce_output_inline;
 use function MongoDB\is_pipeline;
+use function MongoDB\is_write_concern_acknowledged;
 
 /**
  * Unit tests for utility functions.
@@ -255,4 +257,31 @@ public function providePipelines()
             'DbRef in numeric field as object' => [false, (object) ['0' => ['$ref' => 'foo', '$id' => 'bar']]],
         ];
     }
+
+    /**
+     * @dataProvider provideWriteConcerns
+     */
+    public function testIsWriteConcernAcknowledged($expected, WriteConcern $writeConcern): void
+    {
+        $this->assertSame($expected, is_write_concern_acknowledged($writeConcern));
+    }
+
+    public function provideWriteConcerns(): array
+    {
+        // Note: WriteConcern constructor prohibits w=-1 or w=0 and journal=true
+        return [
+            'MONGOC_WRITE_CONCERN_W_MAJORITY' => [true, new WriteConcern(-3)],
+            'MONGOC_WRITE_CONCERN_W_DEFAULT' => [true, new WriteConcern(-2)],
+            'MONGOC_WRITE_CONCERN_W_DEFAULT and journal=true' => [true, new WriteConcern(-2, 0, true)],
+            'MONGOC_WRITE_CONCERN_W_ERRORS_IGNORED' => [false, new WriteConcern(-1)],
+            'MONGOC_WRITE_CONCERN_W_ERRORS_IGNORED and journal=false' => [false, new WriteConcern(-1, 0, false)],
+            'MONGOC_WRITE_CONCERN_W_UNACKNOWLEDGED' => [false, new WriteConcern(0)],
+            'MONGOC_WRITE_CONCERN_W_UNACKNOWLEDGED and journal=false' => [false, new WriteConcern(0, 0, false)],
+            'w=1' => [true, new WriteConcern(1)],
+            'w=1 and journal=false' => [true, new WriteConcern(1, 0, false)],
+            'w=1 and journal=true' => [true, new WriteConcern(1, 0, true)],
+            'majority' => [true, new WriteConcern(WriteConcern::MAJORITY)],
+            'tag' => [true, new WriteConcern('tag')],
+        ];
+    }
 }

tests/Operation/DeleteFunctionalTest.php

@@ -7,6 +7,7 @@
 use MongoDB\Driver\BulkWrite;
 use MongoDB\Driver\WriteConcern;
 use MongoDB\Exception\BadMethodCallException;
+use MongoDB\Exception\UnsupportedException;
 use MongoDB\Operation\Delete;
 use MongoDB\Tests\CommandObserver;
 
@@ -63,6 +64,46 @@ public function testDeleteMany(): void
         $this->assertSameDocuments($expected, $this->collection->find());
     }
 
+    public function testHintOptionUnsupportedClientSideError(): void
+    {
+        if (version_compare($this->getServerVersion(), '3.4.0', '>=')) {
+            $this->markTestSkipped('server reports error for unsupported delete options');
+        }
+
+        $operation = new Delete(
+            $this->getDatabaseName(),
+            $this->getCollectionName(),
+            [],
+            0,
+            ['hint' => '_id_']
+        );
+
+        $this->expectException(UnsupportedException::class);
+        $this->expectExceptionMessage('Hint is not supported by the server executing this operation');
+
+        $operation->execute($this->getPrimaryServer());
+    }
+
+    public function testHintOptionAndUnacknowledgedWriteConcernUnsupportedClientSideError(): void
+    {
+        if (version_compare($this->getServerVersion(), '4.4.0', '>=')) {
+            $this->markTestSkipped('hint is supported');
+        }
+
+        $operation = new Delete(
+            $this->getDatabaseName(),
+            $this->getCollectionName(),
+            [],
+            0,
+            ['hint' => '_id_', 'writeConcern' => new WriteConcern(0)]
+        );
+
+        $this->expectException(UnsupportedException::class);
+        $this->expectExceptionMessage('Hint is not supported by the server executing this operation');
+
+        $operation->execute($this->getPrimaryServer());
+    }
+
     public function testSessionOption(): void
     {
         if (version_compare($this->getServerVersion(), '3.6.0', '<')) {

tests/Operation/FindAndModifyFunctionalTest.php

@@ -4,6 +4,8 @@
 
 use MongoDB\Driver\BulkWrite;
 use MongoDB\Driver\ReadPreference;
+use MongoDB\Driver\WriteConcern;
+use MongoDB\Exception\UnsupportedException;
 use MongoDB\Model\BSONDocument;
 use MongoDB\Operation\FindAndModify;
 use MongoDB\Tests\CommandObserver;
@@ -54,6 +56,42 @@ function (array $event): void {
         );
     }
 
+    public function testHintOptionUnsupportedClientSideError(): void
+    {
+        if (version_compare($this->getServerVersion(), '4.2.0', '>=')) {
+            $this->markTestSkipped('server reports error for unsupported findAndModify options');
+        }
+
+        $operation = new FindAndModify(
+            $this->getDatabaseName(),
+            $this->getCollectionName(),
+            ['remove' => true, 'hint' => '_id_']
+        );
+
+        $this->expectException(UnsupportedException::class);
+        $this->expectExceptionMessage('Hint is not supported by the server executing this operation');
+
+        $operation->execute($this->getPrimaryServer());
+    }
+
+    public function testHintOptionAndUnacknowledgedWriteConcernUnsupportedClientSideError(): void
+    {
+        if (version_compare($this->getServerVersion(), '4.4.0', '>=')) {
+            $this->markTestSkipped('hint is supported');
+        }
+
+        $operation = new FindAndModify(
+            $this->getDatabaseName(),
+            $this->getCollectionName(),
+            ['remove' => true, 'hint' => '_id_', 'writeConcern' => new WriteConcern(0)]
+        );
+
+        $this->expectException(UnsupportedException::class);
+        $this->expectExceptionMessage('Hint is not supported by the server executing this operation');
+
+        $operation->execute($this->getPrimaryServer());
+    }
+
     public function testSessionOption(): void
     {
         if (version_compare($this->getServerVersion(), '3.6.0', '<')) {

tests/Operation/UpdateFunctionalTest.php

@@ -7,6 +7,7 @@
 use MongoDB\Driver\BulkWrite;
 use MongoDB\Driver\WriteConcern;
 use MongoDB\Exception\BadMethodCallException;
+use MongoDB\Exception\UnsupportedException;
 use MongoDB\Operation\Update;
 use MongoDB\Tests\CommandObserver;
 use MongoDB\UpdateResult;
@@ -98,6 +99,46 @@ function (array $event): void {
         );
     }
 
+    public function testHintOptionUnsupportedClientSideError(): void
+    {
+        if (version_compare($this->getServerVersion(), '3.4.0', '>=')) {
+            $this->markTestSkipped('server reports error for unsupported update options');
+        }
+
+        $operation = new Update(
+            $this->getDatabaseName(),
+            $this->getCollectionName(),
+            ['_id' => 1],
+            ['$inc' => ['x' => 1]],
+            ['hint' => '_id_']
+        );
+
+        $this->expectException(UnsupportedException::class);
+        $this->expectExceptionMessage('Hint is not supported by the server executing this operation');
+
+        $operation->execute($this->getPrimaryServer());
+    }
+
+    public function testHintOptionAndUnacknowledgedWriteConcernUnsupportedClientSideError(): void
+    {
+        if (version_compare($this->getServerVersion(), '4.2.0', '>=')) {
+            $this->markTestSkipped('hint is supported');
+        }
+
+        $operation = new Update(
+            $this->getDatabaseName(),
+            $this->getCollectionName(),
+            ['_id' => 1],
+            ['$inc' => ['x' => 1]],
+            ['hint' => '_id_', 'writeConcern' => new WriteConcern(0)]
+        );
+
+        $this->expectException(UnsupportedException::class);
+        $this->expectExceptionMessage('Hint is not supported by the server executing this operation');
+
+        $operation->execute($this->getPrimaryServer());
+    }
+
     public function testUpdateOne(): void
     {
         $this->createFixtures(3);