Extract Database methods to CreateEncryptedCollection operation

jmikola · jmikola · commit f947e6158cce · 2023-03-31T15:47:02.000+08:00
diff --git a/psalm-baseline.xml b/psalm-baseline.xml
@@ -491,6 +491,12 @@
       <code>$options['writeConcern']</code>
     </MixedAssignment>
   </file>
+  <file src="src/Operation/CreateEncryptedCollection.php">
+    <DocblockTypeContradiction occurrences="2">
+      <code>! is_array($encryptedFields['fields'])</code>
+      <code>! is_array($field) &amp;&amp; ! is_object($field)</code>
+    </DocblockTypeContradiction>
+  </file>
   <file src="src/Operation/CreateIndexes.php">
     <DocblockTypeContradiction occurrences="1">
       <code>is_array($index)</code>
diff --git a/src/Database.php b/src/Database.php
@@ -18,7 +18,6 @@
 namespace MongoDB;
 
 use Iterator;
-use MongoDB\BSON\Binary;
 use MongoDB\Driver\ClientEncryption;
 use MongoDB\Driver\Cursor;
 use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
@@ -36,7 +35,7 @@
 use MongoDB\Model\CollectionInfoIterator;
 use MongoDB\Operation\Aggregate;
 use MongoDB\Operation\CreateCollection;
-use MongoDB\Operation\CreateIndexes;
+use MongoDB\Operation\CreateEncryptedCollection;
 use MongoDB\Operation\DatabaseCommand;
 use MongoDB\Operation\DropCollection;
 use MongoDB\Operation\DropDatabase;
@@ -45,13 +44,10 @@
 use MongoDB\Operation\ModifyCollection;
 use MongoDB\Operation\RenameCollection;
 use MongoDB\Operation\Watch;
+use Throwable;
 use Traversable;
-use Exception;
 
-use function array_key_exists;
 use function is_array;
-use function is_object;
-use function property_exists;
 use function strlen;
 
 class Database
@@ -263,7 +259,13 @@ public function command($command, array $options = [])
     /**
      * Create a new collection explicitly.
      *
+     * If the "encryptedFields" option is specified, this method additionally
+     * creates related metadata collections and an index on the encrypted
+     * collection.
+     *
      * @see CreateCollection::__construct() for supported options
+     * @see https://github.com/mongodb/specifications/blob/master/source/client-side-encryption/client-side-encryption.rst#create-collection-helper
+     * @see https://www.mongodb.com/docs/manual/core/queryable-encryption/fundamentals/manage-collections/
      * @return array|object Command result document
      * @throws UnsupportedException if options are not supported by the selected server
      * @throws InvalidArgumentException for parameter/option parsing errors
@@ -275,90 +277,62 @@ public function createCollection(string $collectionName, array $options = [])
             $options['typeMap'] = $this->typeMap;
         }
 
-        $server = select_server($this->manager, $options);
-
         if (! isset($options['writeConcern']) && ! is_in_transaction($options)) {
             $options['writeConcern'] = $this->writeConcern;
         }
 
-        $encryptedFields = $options['encryptedFields']
-            ?? get_encrypted_fields_from_driver($this->databaseName, $collectionName, $this->manager)
-            ?? null;
-
-        if ($encryptedFields !== null) {
-            // encryptedFields is passed to the create command
-            $options['encryptedFields'] = $encryptedFields;
-
-            $encryptedFields = (array) $encryptedFields;
-            $enxcolOptions = ['clusteredIndex' => ['key' => ['_id' => 1], 'unique' => true]];
-            (new CreateCollection($this->databaseName, $encryptedFields['escCollection'] ?? 'enxcol_.' . $collectionName . '.esc', $enxcolOptions))->execute($server);
-            (new CreateCollection($this->databaseName, $encryptedFields['eccCollection'] ?? 'enxcol_.' . $collectionName . '.ecc', $enxcolOptions))->execute($server);
-            (new CreateCollection($this->databaseName, $encryptedFields['ecocCollection'] ?? 'enxcol_.' . $collectionName . '.ecoc', $enxcolOptions))->execute($server);
+        if (! isset($options['encryptedFields'])) {
+            $options['encryptedFields'] = get_encrypted_fields_from_driver($this->databaseName, $collectionName, $this->manager);
         }
 
-        $operation = new CreateCollection($this->databaseName, $collectionName, $options);
+        $operation = isset($options['encryptedFields'])
+            ? new CreateEncryptedCollection($this->databaseName, $collectionName, $options)
+            : new CreateCollection($this->databaseName, $collectionName, $options);
 
-        $result = $operation->execute($server);
-
-        if ($encryptedFields !== null) {
-            (new CreateIndexes($this->databaseName, $collectionName, [['key' => ['__safeContent__' => 1]]]))->execute($server);
-        }
+        $server = select_server($this->manager, $options);
 
-        return $result;
+        return $operation->execute($server);
     }
 
     /**
      * Create a new encrypted collection explicitly.
      *
-     * This function will automatically create data keys for any encrypted
-     * fields where the "keyId" option is null. This function will return a copy
-     * of the modified "encryptedFields" option in addition to the result from
-     * createCollection(). The "encryptedFields" option is required.
+     * The "encryptedFields" option is required.
+     *
+     * This method will automatically create data keys for any encrypted fields
+     * where "keyId" is null. A copy of the modified "encryptedFields" option
+     * will be returned in addition to the result from creating the collection.
      *
-     * If any error is encountered while creating data keys or invoking
-     * createCollection(), a CreateEncryptedCollectionException will be thrown.
-     * The original exception and modified "encryptedFields" option can be
-     * accessed via the getPrevious() and getEncryptedFields() methods,
-     * respectively.
+     * If any error is encountered while creating data keys or creating the
+     * collection, a CreateEncryptedCollectionException will be thrown. The
+     * original exception and modified "encryptedFields" option can be accessed
+     * via the getPrevious() and getEncryptedFields() methods, respectively.
      *
      * @see CreateCollection::__construct() for supported options
-     * @return array A tuple consisting of the createCollection() result and modified "encryptedFields" option
+     * @return array A tuple consisting of the result from creating the collection and the modified "encryptedFields" option
      * @throws InvalidArgumentException for parameter/option parsing errors
-     * @throws CreateEncryptedCollectionException for any errors creating data keys or invoking createCollection()
+     * @throws CreateEncryptedCollectionException for any errors creating data keys or creating the collection
      */
     public function createEncryptedCollection(string $collectionName, ClientEncryption $clientEncryption, string $kmsProvider, ?array $masterKey, array $options): array
     {
-        if (! isset($options['encryptedFields']) || ! is_array($options['encryptedFields']) && ! is_object($options['encryptedFields'])) {
-            throw InvalidArgumentException::invalidType('"encryptedFields" option', $options['encryptedFields'] ?? null, ['array', 'object']);
+        if (! isset($options['typeMap'])) {
+            $options['typeMap'] = $this->typeMap;
         }
 
-        /** @var array{fields: list<array{keyId: ?Binary}|object{keyId: ?Binary}>} */
-        $encryptedFields = (array) recursive_copy($options['encryptedFields']);
+        if (! isset($options['writeConcern']) && ! is_in_transaction($options)) {
+            $options['writeConcern'] = $this->writeConcern;
+        }
 
-        $createDataKeyArgs = [
-            $kmsProvider,
-            isset($masterKey) ? ['masterKey' => $masterKey] : [],
-        ];
+        $operation = new CreateEncryptedCollection($this->databaseName, $collectionName, $options);
+        $server = select_server($this->manager, $options);
 
         try {
-            /** @psalm-suppress RedundantConditionGivenDocblockType */
-            if (isset($encryptedFields['fields']) && is_array($encryptedFields['fields'])) {
-                foreach ($encryptedFields['fields'] as &$field) {
-                    if (is_array($field) && array_key_exists('keyId', $field) && $field['keyId'] === null) {
-                        $field['keyId'] = $clientEncryption->createDataKey(...$createDataKeyArgs);
-                    } elseif (is_object($field) && property_exists($field, 'keyId') && $field->keyId === null) {
-                        $field->keyId = $clientEncryption->createDataKey(...$createDataKeyArgs);
-                    }
-                }
-
-                $options['encryptedFields'] = $encryptedFields;
-            }
-
-            $result = $this->createCollection($collectionName, $options);
+            $operation->createDataKeys($clientEncryption, $kmsProvider, $masterKey, $encryptedFields);
+            $result = $operation->execute($server);
 
             return [$result, $encryptedFields];
-        } catch (Exception $e) {
-            throw new CreateEncryptedCollectionException($e, $encryptedFields);
+        } catch (Throwable $e) {
+            throw new CreateEncryptedCollectionException($e, $encryptedFields ?? []);
         }
     }
 
diff --git a/src/Operation/CreateEncryptedCollection.php b/src/Operation/CreateEncryptedCollection.php
@@ -0,0 +1,167 @@
+<?php
+/*
+ * Copyright 2023-present 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
+ *
+ *   https://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\Operation;
+
+// phpcs:disable SlevomatCodingStandard.Namespaces.UnusedUses.UnusedUse
+use MongoDB\BSON\Binary;
+// phpcs:enable
+use MongoDB\Driver\ClientEncryption;
+use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
+use MongoDB\Driver\Server;
+use MongoDB\Exception\InvalidArgumentException;
+
+use function array_key_exists;
+use function is_array;
+use function is_object;
+
+/**
+ * Create an encrypted collection.
+ *
+ * The "encryptedFields" option is required.
+ *
+ * This operation additionally creates related metadata collections and an index
+ * on the encrypted collection.
+ *
+ * @internal
+ * @see \MongoDB\Database::createCollection()
+ * @see \MongoDB\Database::createEncryptedCollection()
+ * @see https://github.com/mongodb/specifications/blob/master/source/client-side-encryption/client-side-encryption.rst#create-collection-helper
+ * @see https://www.mongodb.com/docs/manual/core/queryable-encryption/fundamentals/manage-collections/
+ */
+class CreateEncryptedCollection implements Executable
+{
+    /** @var CreateCollection */
+    private $createCollection;
+
+    /** @var CreateCollection[] */
+    private $createMetadataCollections;
+
+    /** @var CreateIndexes */
+    private $createSafeContentIndex;
+
+    /** @var string */
+    private $databaseName;
+
+    /** @var string */
+    private $collectionName;
+
+    /** @var array */
+    private $options;
+
+    /**
+     * @see CreateCollection::__construct() for supported options
+     * @param string $databaseName   Database name
+     * @param string $collectionName Collection name
+     * @param array  $options        CreateCollection options
+     * @throws InvalidArgumentException for parameter/option parsing errors
+     */
+    public function __construct(string $databaseName, string $collectionName, array $options)
+    {
+        if (! isset($options['encryptedFields'])) {
+            throw new InvalidArgumentException('"encryptedFields" option is required');
+        }
+
+        if (! is_array($options['encryptedFields']) && ! is_object($options['encryptedFields'])) {
+            throw InvalidArgumentException::invalidType('"encryptedFields" option', $options['encryptedFields'], 'array or object');
+        }
+
+        $this->createCollection = new CreateCollection($databaseName, $collectionName, $options);
+
+        /** @psalm-var array{eccCollection?: ?string, ecocCollection?: ?string, escCollection?: ?string} */
+        $encryptedFields = (array) $options['encryptedFields'];
+        $enxcolOptions = ['clusteredIndex' => ['key' => ['_id' => 1], 'unique' => true]];
+
+        $this->createMetadataCollections = [
+            new CreateCollection($databaseName, $encryptedFields['escCollection'] ?? 'enxcol_.' . $collectionName . '.esc', $enxcolOptions),
+            new CreateCollection($databaseName, $encryptedFields['eccCollection'] ?? 'enxcol_.' . $collectionName . '.ecc', $enxcolOptions),
+            new CreateCollection($databaseName, $encryptedFields['ecocCollection'] ?? 'enxcol_.' . $collectionName . '.ecoc', $enxcolOptions),
+        ];
+
+        $this->createSafeContentIndex = new CreateIndexes($databaseName, $collectionName, [['key' => ['__safeContent__' => 1]]]);
+
+        $this->databaseName = $databaseName;
+        $this->collectionName = $collectionName;
+        $this->options = $options;
+    }
+
+    /**
+     * @see Executable::execute()
+     * @return array|object Command result document from creating the encrypted collection
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
+     */
+    public function execute(Server $server)
+    {
+        foreach ($this->createMetadataCollections as $createMetadataCollection) {
+            $createMetadataCollection->execute($server);
+        }
+
+        $result = $this->createCollection->execute($server);
+
+        $this->createSafeContentIndex->execute($server);
+
+        return $result;
+    }
+
+    /**
+     * Create data keys for any encrypted fields where "keyId" is null.
+     *
+     * This method should be called before execute(), as it may modify the
+     * "encryptedFields" option and reconstruct the internal CreateCollection
+     * operation used for creating the encrypted collection.
+     *
+     * The $encryptedFields reference parameter may be used to determine which
+     * data keys have been created.
+     *
+     * @see \MongoDB\Database::createEncryptedCollection()
+     * @see https://www.php.net/manual/en/mongodb-driver-clientencryption.createdatakey.php
+     * @throws DriverRuntimeException for errors creating a data key
+     */
+    public function createDataKeys(ClientEncryption $clientEncryption, string $kmsProvider, ?array $masterKey, ?array &$encryptedFields = null): void
+    {
+        /** @psalm-var array{fields: list<array{keyId: ?Binary}|object{keyId: ?Binary}>} */
+        $encryptedFields = (array) $this->options['encryptedFields'];
+
+        /* NOP if there are no fields to examine. If the type is invalid, defer
+         * to the server to raise an error in execute(). */
+        if (! isset($encryptedFields['fields']) || ! is_array($encryptedFields['fields'])) {
+            return;
+        }
+
+        $createDataKeyArgs = [
+            $kmsProvider,
+            $masterKey !== null ? ['masterKey' => $masterKey] : [],
+        ];
+
+        foreach ($encryptedFields['fields'] as $i => $field) {
+            // Skip invalid types and defer to the server to raise an error
+            if (! is_array($field) && ! is_object($field)) {
+                continue;
+            }
+
+            $field = (array) $field;
+
+            if (array_key_exists('keyId', $field) && $field['keyId'] === null) {
+                $field['keyId'] = $clientEncryption->createDataKey(...$createDataKeyArgs);
+                $encryptedFields['fields'][$i] = $field;
+            }
+        }
+
+        $this->options['encryptedFields'] = $encryptedFields;
+        $this->createCollection = new CreateCollection($this->databaseName, $this->collectionName, $this->options);
+    }
+}
diff --git a/tests/Exception/CreateEncryptedCollectionExceptionTest.php b/tests/Exception/CreateEncryptedCollectionExceptionTest.php
@@ -0,0 +1,25 @@
+<?php
+
+namespace MongoDB\Tests\Exception;
+
+use Exception;
+use MongoDB\Tests\TestCase;
+
+class CreateEncryptedCollectionExceptionTest extends TestCase
+{
+    public function testGetEncryptedFields(): void
+    {
+        $encryptedFields = ['fields' => []];
+
+        $e = new CreateEncryptedCollection(new Exception(), $encryptedFields);
+        $this->assertSame($encryptedFields, $e->getEncryptedFields());
+    }
+
+    public function testGetPrevious(): void
+    {
+        $previous = new Exception();
+
+        $e = new CreateEncryptedCollection($previous, ['fields' => []]);
+        $this->assertSame($previous, $e->getPrevious());
+    }
+}
diff --git a/tests/Operation/CreateEncryptedCollectionTest.php b/tests/Operation/CreateEncryptedCollectionTest.php
