diff --git a/src/Client.php b/src/Client.php index 99d0fb8aa9..d81fec8784 100644 --- a/src/Client.php +++ b/src/Client.php @@ -3,6 +3,7 @@ namespace Utopia\Mongo; use MongoDB\BSON\Document; +use MongoDB\BSON\Int64; use MongoDB\Driver\Exception\InvalidArgumentException; use Ramsey\Uuid\Uuid; use stdClass; @@ -22,6 +23,26 @@ class Client */ private SwooleClient|CoroutineClient $client; + /** + * Active sessions with transaction state tracking. + */ + private array $sessions = []; + + /** + * Current cluster time for causal consistency. + */ + private ?object $clusterTime = null; + + /** + * Current operation time for causal consistency. + */ + private ?object $operationTime = null; + + /** + * Connection status flag. + */ + private bool $isConnected = false; + /** * Defines commands Mongo uses over wire protocol. */ @@ -49,6 +70,33 @@ class Client // Connection and performance settings private int $defaultMaxTimeMS = 30000; // 30 seconds default + // Transaction error codes for retry logic + public const TRANSIENT_TRANSACTION_ERROR = 'TransientTransactionError'; + public const UNKNOWN_TRANSACTION_COMMIT_RESULT = 'UnknownTransactionCommitResult'; + public const TRANSACTION_TIMEOUT_ERROR = 50; + public const TRANSACTION_ABORTED_ERROR = 251; + + // Transaction states + public const TRANSACTION_NONE = 'none'; + public const TRANSACTION_STARTING = 'starting'; + public const TRANSACTION_IN_PROGRESS = 'in_progress'; + public const TRANSACTION_COMMITTED = 'committed'; + public const TRANSACTION_ABORTED = 'aborted'; + + // Read concerns + public const READ_CONCERN_LOCAL = 'local'; + public const READ_CONCERN_AVAILABLE = 'available'; + public const READ_CONCERN_MAJORITY = 'majority'; + public const READ_CONCERN_LINEARIZABLE = 'linearizable'; + public const READ_CONCERN_SNAPSHOT = 'snapshot'; + + // Read preferences + public const READ_PREFERENCE_PRIMARY = 'primary'; + public const READ_PREFERENCE_SECONDARY = 'secondary'; + public const READ_PREFERENCE_PRIMARY_PREFERRED = 'primaryPreferred'; + public const READ_PREFERENCE_SECONDARY_PREFERRED = 'secondaryPreferred'; + public const READ_PREFERENCE_NEAREST = 'nearest'; + /** * Authentication for connection @@ -149,10 +197,25 @@ class Client if ($this->client->isConnected()) { return $this; } + + // Validate connection parameters before attempting connection + $validateConnectionParams = function () { + if (empty($this->host)) { + throw new Exception('MongoDB host cannot be empty'); + } + if ($this->port <= 0 || $this->port > 65535) { + throw new Exception('MongoDB port must be between 1 and 65535'); + } + }; + + $validateConnectionParams(); + if (!$this->client->connect($this->host, $this->port)) { throw new Exception("Failed to connect to MongoDB at {$this->host}:{$this->port}"); } + $this->isConnected = true; + [$payload, $db] = $this->auth->start(); $res = $this->query($payload, $db); @@ -175,22 +238,93 @@ class Client } /** - * Send a BSON packed query to connection. + * Send a BSON packed query to connection with comprehensive session, causal consistency, and transaction support. * - * @param array $command - * @param string|null $db - * @return stdClass|array|int + * @param array $command Command to execute + * @param string|null $db Database name + * @return stdClass|array|int Query result * @throws Exception */ public function query(array $command, ?string $db = null): stdClass|array|int { + // Validate connection state before each operation + $this->validateConnection(); + + $sessionId = null; + + // Extract and process session from options if provided + if (isset($command['session'])) { + $sessionData = $command['session']; + unset($command['session']); + + // Handle different session formats + if (is_array($sessionData) && isset($sessionData['id'])) { + $command['lsid'] = $sessionData['id']; + $rawId = $sessionData['id']->id ?? null; + $sessionId = $rawId instanceof \MongoDB\BSON\Binary + ? bin2hex($rawId->getData()) + : $rawId; + } else { + $command['lsid'] = $sessionData; + $rawId = $sessionData->id ?? null; + $sessionId = $rawId instanceof \MongoDB\BSON\Binary + ? bin2hex($rawId->getData()) + : $rawId; + } + + // Add transaction parameters if session is in transaction + if ($sessionId && isset($this->sessions[$sessionId]) && + $this->sessions[$sessionId]['state'] === self::TRANSACTION_IN_PROGRESS) { + $command['txnNumber'] = new Int64($this->sessions[$sessionId]['txnNumber']); + $command['autocommit'] = false; + + // Add the first operation flag for the first operation in the transaction + if (!isset($this->sessions[$sessionId]['firstOperationDone'])) { + $command['startTransaction'] = true; + $this->sessions[$sessionId]['firstOperationDone'] = true; + + // Add transaction options from startTransaction + if (isset($this->sessions[$sessionId]['transactionOptions'])) { + $txnOpts = $this->sessions[$sessionId]['transactionOptions']; + if (isset($txnOpts['readConcern'])) { + $command['readConcern'] = $txnOpts['readConcern']; + } + if (isset($txnOpts['writeConcern'])) { + $command['writeConcern'] = $txnOpts['writeConcern']; + } + } + } + } + } + + // Add causal consistency support + if ($this->operationTime !== null && !isset($command['readConcern']['afterClusterTime'])) { + $command['readConcern'] = $command['readConcern'] ?? []; + $command['readConcern']['afterClusterTime'] = $this->operationTime; + } + + // Add cluster time for causal consistency + if ($this->clusterTime !== null) { + $command['$clusterTime'] = $this->clusterTime; + } + $params = array_merge($command, [ '$db' => $db ?? $this->database, ]); $sections = Document::fromPHP($params); $message = pack('V*', 21 + strlen($sections), $this->id, 0, 2013, 0) . "\0" . $sections; - return $this->send($message); + $result = $this->send($message); + + // Update causal consistency timestamps from response + $this->updateCausalConsistency($result); + + // Update session last use time if session was provided + if ($sessionId && isset($this->sessions[$sessionId])) { + $this->sessions[$sessionId]['lastUse'] = time(); + } + + return $result; } @@ -450,14 +584,20 @@ class Client } /** - * Insert document. + * Insert document with full transaction and session support. * https://docs.mongodb.com/manual/reference/command/insert/#mongodb-dbcommand-dbcmd.insert * - * @param string $collection - * @param array $document - * @param array $options + * @param string $collection Collection name + * @param array $document Document to insert + * @param array $options Options array supporting: + * - session: Session object for transactions + * - writeConcern: Write concern specification + * - readConcern: Read concern specification + * - readPreference: Read preference + * - maxTimeMS: Operation timeout in milliseconds + * - ordered: Whether to stop on first error (default: true) * - * @return array + * @return array Inserted document with _id * @throws Exception */ public function insert(string $collection, array $document, array $options = []): array @@ -472,21 +612,50 @@ class Client $docObj->_id = $this->createUuid(); } - $this->query(array_merge([ + // Build command with session and concerns + $command = [ self::COMMAND_INSERT => $collection, 'documents' => [$docObj], - ], $options)); + ]; + + // Add session if provided + if (isset($options['session'])) { + $command['session'] = $options['session']; + } + + // Add write concern if provided with validation + if (isset($options['writeConcern'])) { + $command['writeConcern'] = $this->createWriteConcern($options['writeConcern']); + } + + // Add read concern if provided with validation + if (isset($options['readConcern'])) { + $command['readConcern'] = $this->createReadConcern($options['readConcern']); + } + + // Add other options (excluding those we've already handled) + $otherOptions = array_diff_key($options, array_flip(['session', 'writeConcern', 'readConcern'])); + $command = array_merge($command, $otherOptions); + + $this->query($command); return $this->toArray($docObj); } /** * Insert multiple documents with improved batching for MongoDB 8+ performance. - * Automatically handles large datasets by batching operations. + * Automatically handles large datasets by batching operations with full transaction support. * * @param string $collection Collection name * @param array $documents Array of documents to insert - * @param array $options Options (ordered, writeConcern, batchSize, etc.) + * @param array $options Options array supporting: + * - session: Session object for transactions + * - writeConcern: Write concern specification + * - readConcern: Read concern specification + * - readPreference: Read preference + * - maxTimeMS: Operation timeout in milliseconds + * - ordered: Whether to stop on first error (default: true) + * - batchSize: Number of documents per batch (default: 1000) * @return array Array of inserted documents with generated _ids * @throws Exception */ @@ -520,12 +689,33 @@ class Client $docObjs[] = $docObj; } - $batchOptions = array_diff_key($options, array_flip(['batchSize'])); - $this->query(array_merge([ + // Build command with session and concerns + $command = [ self::COMMAND_INSERT => $collection, 'documents' => $docObjs, 'ordered' => $ordered, - ], $batchOptions)); + ]; + + // Add session if provided + if (isset($options['session'])) { + $command['session'] = $options['session']; + } + + // Add write concern if provided with validation + if (isset($options['writeConcern'])) { + $command['writeConcern'] = $this->createWriteConcern($options['writeConcern']); + } + + // Add read concern if provided with validation + if (isset($options['readConcern'])) { + $command['readConcern'] = $this->createReadConcern($options['readConcern']); + } + + // Add other options (excluding those we've already handled) + $otherOptions = array_diff_key($options, array_flip(['session', 'writeConcern', 'readConcern', 'batchSize'])); + $command = array_merge($command, $otherOptions); + + $this->query($command); $insertedDocs = array_merge($insertedDocs, $this->toArray($docObjs)); } @@ -553,33 +743,60 @@ class Client } /** - * Update a document/s. + * Update document(s) with full transaction and session support. * https://docs.mongodb.com/manual/reference/command/update/#syntax * - * @param string $collection - * @param array $where - * @param array $updates - * @param array $options - * @param bool $multi + * @param string $collection Collection name + * @param array $where Filter criteria + * @param array $updates Update operations + * @param array $options Options array supporting: + * - session: Session object for transactions + * - writeConcern: Write concern specification + * - readConcern: Read concern specification + * - readPreference: Read preference + * - maxTimeMS: Operation timeout in milliseconds + * - upsert: Whether to insert if no match found + * - arrayFilters: Array filters for updates + * @param bool $multi Whether to update multiple documents * * @return Client * @throws Exception */ public function update(string $collection, array $where = [], array $updates = [], array $options = [], bool $multi = false): self { - $this->query( - array_merge([ - self::COMMAND_UPDATE => $collection, - 'updates' => [ - [ - 'q' => $this->toObject($where), - 'u' => $this->toObject($updates), - 'multi' => $multi, - 'upsert' => false - ] + // Build command with session and concerns + $command = [ + self::COMMAND_UPDATE => $collection, + 'updates' => [ + [ + 'q' => $this->toObject($where), + 'u' => $this->toObject($updates), + 'multi' => $multi, + 'upsert' => $options['upsert'] ?? false ] - ], $options) - ); + ] + ]; + + // Add session if provided + if (isset($options['session'])) { + $command['session'] = $options['session']; + } + + // Add write concern if provided with validation + if (isset($options['writeConcern'])) { + $command['writeConcern'] = $this->createWriteConcern($options['writeConcern']); + } + + // Add read concern if provided with validation + if (isset($options['readConcern'])) { + $command['readConcern'] = $this->createReadConcern($options['readConcern']); + } + + // Add other options (excluding those we've already handled) + $otherOptions = array_diff_key($options, array_flip(['session', 'writeConcern', 'readConcern', 'upsert'])); + $command = array_merge($command, $otherOptions); + + $this->query($command); return $this; } @@ -624,12 +841,22 @@ class Client /** - * Find a document/s. + * Find document(s) with full transaction and session support. * https://docs.mongodb.com/manual/reference/command/find/#mongodb-dbcommand-dbcmd.find * * @param string $collection Collection name * @param array $filters Query filters - * @param array $options Query options + * @param array $options Options array supporting: + * - session: Session object for transactions + * - readConcern: Read concern specification + * - readPreference: Read preference + * - maxTimeMS: Operation timeout in milliseconds + * - limit: Maximum number of documents to return + * - skip: Number of documents to skip + * - sort: Sort specification + * - projection: Field projection specification + * - hint: Index hint + * - allowPartialResults: Allow partial results from sharded clusters * @return stdClass Query result * @throws Exception */ @@ -637,31 +864,81 @@ class Client { $filters = $this->cleanFilters($filters); - return $this->query( - array_merge([ - self::COMMAND_FIND => $collection, - 'filter' => $this->toObject($filters), - ], $options) - ); + // Build command with session and concerns + $command = [ + self::COMMAND_FIND => $collection, + 'filter' => $this->toObject($filters), + ]; + + // Add session if provided + if (isset($options['session'])) { + $command['session'] = $options['session']; + } + + // Add read concern if provided with validation + if (isset($options['readConcern'])) { + $command['readConcern'] = $this->createReadConcern($options['readConcern']); + } + + // Add read preference if provided + if (isset($options['readPreference'])) { + $command['$readPreference'] = $options['readPreference']; + } + + // Add other options (excluding those we've already handled) + $otherOptions = array_diff_key($options, array_flip(['session', 'readConcern', 'readPreference'])); + $command = array_merge($command, $otherOptions); + + return $this->query($command); } /** - * Aggregate a collection pipeline. + * Aggregate a collection pipeline with full transaction and session support. * - * @param string $collection - * @param array $pipeline - * @param array $options + * @param string $collection Collection name + * @param array $pipeline Aggregation pipeline + * @param array $options Options array supporting: + * - session: Session object for transactions + * - readConcern: Read concern specification + * - readPreference: Read preference + * - maxTimeMS: Operation timeout in milliseconds + * - allowDiskUse: Allow using disk for large result sets + * - batchSize: Batch size for cursor + * - hint: Index hint + * - explain: Return query execution plan * - * @return stdClass + * @return stdClass Aggregation result * @throws Exception */ public function aggregate(string $collection, array $pipeline, array $options = []): stdClass { - return $this->query(array_merge([ + // Build command with session and concerns + $command = [ self::COMMAND_AGGREGATE => $collection, 'pipeline' => $pipeline, 'cursor' => $this->toObject([]), - ], $options)); + ]; + + // Add session if provided + if (isset($options['session'])) { + $command['session'] = $options['session']; + } + + // Add read concern if provided with validation + if (isset($options['readConcern'])) { + $command['readConcern'] = $this->createReadConcern($options['readConcern']); + } + + // Add read preference if provided + if (isset($options['readPreference'])) { + $command['$readPreference'] = $options['readPreference']; + } + + // Add other options (excluding those we've already handled) + $otherOptions = array_diff_key($options, array_flip(['session', 'readConcern', 'readPreference'])); + $command = array_merge($command, $otherOptions); + + return $this->query($command); } /** @@ -709,49 +986,79 @@ class Client } /** - * Delete a document/s. + * Delete document(s) with full transaction and session support. * https://docs.mongodb.com/manual/reference/command/delete/#mongodb-dbcommand-dbcmd.delete * - * @param string $collection - * @param array $filters - * @param int $limit - * @param array $deleteOptions - * @param array $options + * @param string $collection Collection name + * @param array $filters Delete filters + * @param int $limit Maximum number of documents to delete + * @param array $deleteOptions Delete operation options + * @param array $options Options array supporting: + * - session: Session object for transactions + * - writeConcern: Write concern specification + * - readConcern: Read concern specification + * - readPreference: Read preference + * - maxTimeMS: Operation timeout in milliseconds + * - hint: Index hint * - * @return int + * @return int Number of deleted documents * @throws Exception */ public function delete(string $collection, array $filters = [], int $limit = 1, array $deleteOptions = [], array $options = []): int { - return $this->query( - array_merge( - [ - self::COMMAND_DELETE => $collection, - 'deletes' => [ - $this->toObject( - array_merge( - [ - 'q' => $this->toObject($filters), - 'limit' => $limit, - ], - $deleteOptions - ) - ), - ] - ], - $options - ) - ); + // Build command with session and concerns + $command = [ + self::COMMAND_DELETE => $collection, + 'deletes' => [ + $this->toObject( + array_merge( + [ + 'q' => $this->toObject($filters), + 'limit' => $limit, + ], + $deleteOptions + ) + ), + ] + ]; + + // Add session if provided + if (isset($options['session'])) { + $command['session'] = $options['session']; + } + + // Add write concern if provided with validation + if (isset($options['writeConcern'])) { + $command['writeConcern'] = $this->createWriteConcern($options['writeConcern']); + } + + // Add read concern if provided with validation + if (isset($options['readConcern'])) { + $command['readConcern'] = $this->createReadConcern($options['readConcern']); + } + + // Add other options (excluding those we've already handled) + $otherOptions = array_diff_key($options, array_flip(['session', 'writeConcern', 'readConcern'])); + $command = array_merge($command, $otherOptions); + + return $this->query($command); } /** - * Count documents. + * Count documents with full transaction and session support. * - * @param string $collection - * @param array $filters - * @param array $options + * @param string $collection Collection name + * @param array $filters Query filters + * @param array $options Options array supporting: + * - session: Session object for transactions + * - readConcern: Read concern specification + * - readPreference: Read preference + * - maxTimeMS: Operation timeout in milliseconds + * - limit: Maximum number of documents to count + * - skip: Number of documents to skip + * - hint: Index hint * - * @return int + * @return int Number of matching documents * @throws Exception */ public function count(string $collection, array $filters, array $options): int @@ -764,6 +1071,21 @@ class Client 'query' => $this->toObject($filters), ]; + // Add session if provided + if (isset($options['session'])) { + $command['session'] = $options['session']; + } + + // Add read concern if provided with validation + if (isset($options['readConcern'])) { + $command['readConcern'] = $this->createReadConcern($options['readConcern']); + } + + // Add read preference if provided + if (isset($options['readPreference'])) { + $command['$readPreference'] = $options['readPreference']; + } + // Add limit if specified if (isset($options['limit'])) { $command['limit'] = (int)$options['limit']; @@ -779,6 +1101,10 @@ class Client $command['maxTimeMS'] = (int)$options['maxTimeMS']; } + // Add other options (excluding those we've already handled) + $otherOptions = array_diff_key($options, array_flip(['session', 'readConcern', 'readPreference', 'limit', 'skip', 'maxTimeMS'])); + $command = array_merge($command, $otherOptions); + try { $result = $this->query($command); return (int)$result; @@ -789,87 +1115,270 @@ class Client /** - * Start a new logical session. Returns the session id object.. + * Start a new logical session with comprehensive state tracking for transactions. * - * @return object + * @param array $options Session options supporting: + * - causalConsistency: Enable causal consistency (default: true) + * - defaultTransactionOptions: Default transaction options + * @return array Session object with comprehensive state tracking * @throws Exception */ - public function startSession(): object + public function startSession(array $options = []): array { + $sessionOptions = [ + 'causalConsistency' => $options['causalConsistency'] ?? true + ]; + + if (isset($options['defaultTransactionOptions'])) { + $sessionOptions['defaultTransactionOptions'] = $options['defaultTransactionOptions']; + } + $result = $this->query([ - self::COMMAND_START_SESSION => 1 + self::COMMAND_START_SESSION => 1, + 'options' => $sessionOptions ], 'admin'); - return $result->id->id; + // Convert BSON\Binary to string for use as array key + $sessionId = $result->id->id instanceof \MongoDB\BSON\Binary + ? bin2hex($result->id->id->getData()) + : (string)$result->id->id; + + // Initialize session state tracking + $this->sessions[$sessionId] = [ + 'id' => $result->id, + 'state' => self::TRANSACTION_NONE, + 'txnNumber' => 0, + 'lastUse' => time(), + 'operationTime' => null, + 'clusterTime' => null, + 'options' => $sessionOptions, + 'retryableWriteNumber' => 0 + ]; + + return ['id' => $result->id, 'sessionId' => $sessionId]; } /** - * Commit a transaction. + * Start a new transaction on a session with comprehensive state management. * - * @param array $lsid - * @param int $txnNumber - * @param bool $autocommit - * @return mixed + * @param array $session Session from startSession() + * @param array $options Transaction options supporting: + * - readConcern: Read concern specification + * - writeConcern: Write concern specification + * - readPreference: Read preference + * - maxCommitTimeMS: Maximum time to allow for commit + * @return bool Success status * @throws Exception */ - public function commitTransaction(array $lsid, int $txnNumber, bool $autocommit = false) + public function startTransaction(array $session, array $options = []): bool { - $txnNumber = new \MongoDB\BSON\Int64($txnNumber); + $rawId = $session['sessionId'] ?? ($session['id']->id ?? null); + $sessionId = $rawId instanceof \MongoDB\BSON\Binary + ? bin2hex($rawId->getData()) + : $rawId; - $result = $this->query([ + if (!$sessionId || !isset($this->sessions[$sessionId])) { + throw new Exception('Invalid session provided to startTransaction'); + } + + $sessionState = &$this->sessions[$sessionId]; + + // Check current transaction state + if ($sessionState['state'] === self::TRANSACTION_IN_PROGRESS) { + throw new Exception('Session already has a transaction in progress'); + } + + // Increment transaction number for new transaction + $sessionState['txnNumber']++; + + // In MongoDB, transactions are started implicitly with the first operation + // We just need to update the session state and store the options + $sessionState['state'] = self::TRANSACTION_IN_PROGRESS; + $sessionState['lastUse'] = time(); + + // Store transaction options for use with actual operations + $sessionState['transactionOptions'] = []; + + // Store read/write concerns if provided + if (isset($options['readConcern'])) { + $sessionState['transactionOptions']['readConcern'] = $options['readConcern']; + } + if (isset($options['writeConcern'])) { + $sessionState['transactionOptions']['writeConcern'] = $options['writeConcern']; + } + if (isset($options['readPreference'])) { + $sessionState['transactionOptions']['readPreference'] = $options['readPreference']; + } + if (isset($options['maxCommitTimeMS'])) { + $sessionState['transactionOptions']['maxCommitTimeMS'] = $options['maxCommitTimeMS']; + } + + return true; + } + + /** + * Commit a transaction with comprehensive state management and retry support. + * + * @param array $session Session from startSession() + * @param array $options Commit options supporting: + * - writeConcern: Write concern specification + * - maxTimeMS: Maximum time for commit operation + * @return mixed Commit result + * @throws Exception + */ + public function commitTransaction(array $session, array $options = []) + { + $rawId = $session['sessionId'] ?? ($session['id']->id ?? null); + $sessionId = $rawId instanceof \MongoDB\BSON\Binary + ? bin2hex($rawId->getData()) + : $rawId; + + if (!$sessionId || !isset($this->sessions[$sessionId])) { + throw new Exception('Invalid session provided to commitTransaction'); + } + + $sessionState = &$this->sessions[$sessionId]; + + // Check current transaction state + if ($sessionState['state'] !== self::TRANSACTION_IN_PROGRESS) { + throw new Exception('No active transaction to commit'); + } + + $command = [ self::COMMAND_COMMIT_TRANSACTION => 1, - 'lsid' => $lsid, - 'txnNumber' => $txnNumber, - 'autocommit' => $autocommit - ], 'admin'); + 'lsid' => $sessionState['id'], + 'txnNumber' => new Int64($sessionState['txnNumber']), + 'autocommit' => false + ]; - // End the session after successful commit - $this->endSessions([$lsid]); + // Add write concern if provided + if (isset($options['writeConcern'])) { + $command['writeConcern'] = $options['writeConcern']; + } - return $result; + // Add maxTimeMS if provided + if (isset($options['maxTimeMS'])) { + $command['maxTimeMS'] = $options['maxTimeMS']; + } + + try { + $result = $this->query($command, 'admin'); + + if ($result->ok === 1.0) { + $sessionState['state'] = self::TRANSACTION_COMMITTED; + $sessionState['lastUse'] = time(); + unset($sessionState['firstOperationDone']); // Reset for next transaction + } else { + $sessionState['state'] = self::TRANSACTION_ABORTED; + } + + return $result; + } catch (Exception $e) { + // Handle specific commit errors + if ($this->isTransientTransactionError($e) || $this->isUnknownTransactionCommitResult($e)) { + // Keep transaction state for retry + throw $e; + } + + $sessionState['state'] = self::TRANSACTION_ABORTED; + throw $e; + } } /** - * Abort (rollback) a transaction. + * Abort (rollback) a transaction with comprehensive state management. * - * @param array $lsid - * @param int $txnNumber - * @param bool $autocommit - * @return mixed + * @param array $session Session from startSession() + * @param array $options Abort options supporting: + * - maxTimeMS: Maximum time for abort operation + * @return mixed Abort result * @throws Exception */ - public function abortTransaction(array $lsid, int $txnNumber, bool $autocommit = false) + public function abortTransaction(array $session, array $options = []) { - $txnNumber = new \MongoDB\BSON\Int64($txnNumber); + $rawId = $session['sessionId'] ?? ($session['id']->id ?? null); + $sessionId = $rawId instanceof \MongoDB\BSON\Binary + ? bin2hex($rawId->getData()) + : $rawId; - $result = $this->query([ + if (!$sessionId || !isset($this->sessions[$sessionId])) { + throw new Exception('Invalid session provided to abortTransaction'); + } + + $sessionState = &$this->sessions[$sessionId]; + + // Check current transaction state + if ($sessionState['state'] !== self::TRANSACTION_IN_PROGRESS && + $sessionState['state'] !== self::TRANSACTION_STARTING) { + throw new Exception('No active transaction to abort'); + } + + $command = [ self::COMMAND_ABORT_TRANSACTION => 1, - 'lsid' => $lsid, - 'txnNumber' => $txnNumber, - 'autocommit' => $autocommit - ], 'admin'); + 'lsid' => $sessionState['id'], + 'txnNumber' => new Int64($sessionState['txnNumber']), + 'autocommit' => false + ]; - // End the session after successful rollback - $this->endSessions([$lsid]); + // Add maxTimeMS if provided + if (isset($options['maxTimeMS'])) { + $command['maxTimeMS'] = $options['maxTimeMS']; + } - return $result; + try { + $result = $this->query($command, 'admin'); + $sessionState['state'] = self::TRANSACTION_ABORTED; + $sessionState['lastUse'] = time(); + unset($sessionState['firstOperationDone']); // Reset for next transaction + return $result; + } catch (Exception $e) { + // Even if abort fails, mark transaction as aborted + $sessionState['state'] = self::TRANSACTION_ABORTED; + unset($sessionState['firstOperationDone']); // Reset for next transaction + throw $e; + } } /** - * End sessions. + * End sessions with proper state cleanup and validation. * - * @param array $lsids - * @param array $options - * @return mixed + * @param array $sessions Array of session objects from startSession() + * @param array $options End session options + * @return mixed Result of end sessions command * @throws Exception */ - public function endSessions(array $lsids, array $options = []) + public function endSessions(array $sessions, array $options = []) { - // Extract session IDs from the format ['id' => sessionId] and format as objects - $sessionIds = array_map(function ($lsid) { - $sessionId = $lsid['id'] ?? $lsid; - return ['id' => $sessionId]; - }, $lsids); + $sessionIds = []; + + foreach ($sessions as $session) { + $rawId = $session['sessionId'] ?? ($session['id']->id ?? null); + $sessionId = $rawId instanceof \MongoDB\BSON\Binary + ? bin2hex($rawId->getData()) + : $rawId; + + if ($sessionId && isset($this->sessions[$sessionId])) { + $sessionState = $this->sessions[$sessionId]; + + // Warn about active transactions + if ($sessionState['state'] === self::TRANSACTION_IN_PROGRESS) { + error_log("Warning: Ending session with active transaction. Transaction will be aborted."); + } + + $sessionIds[] = $sessionState['id']; + + // Clean up local session state + unset($this->sessions[$sessionId]); + } else { + // Handle legacy format + $sessionId = $session['id'] ?? $session; + $sessionIds[] = $sessionId; + } + } + + if (empty($sessionIds)) { + return new \stdClass(); // Return empty result if no valid sessions + } return $this->query( array_merge( @@ -913,7 +1422,7 @@ class Client } if (is_object($obj) || is_array($obj)) { - $ret = (array) $obj; + $ret = (array)$obj; foreach ($ret as $item) { $item = $this->toArray($item); } @@ -969,13 +1478,35 @@ class Client } /** - * Close connection and clean up resources. + * Close connection and clean up resources including active sessions. */ public function close(): void { + // End any active sessions before closing connection + if (!empty($this->sessions)) { + try { + $activeSessions = []; + foreach ($this->sessions as $sessionId => $sessionData) { + $activeSessions[] = ['id' => $sessionData['id'], 'sessionId' => $sessionId]; + } + + if (!empty($activeSessions)) { + $this->endSessions($activeSessions); + } + } catch (Exception $e) { + // Log error but don't prevent closing + error_log("Error ending sessions during close: " . $e->getMessage()); + } + } + if (isset($this->client) && $this->client->isConnected()) { $this->client->close(); } + + $this->isConnected = false; + $this->sessions = []; + $this->clusterTime = null; + $this->operationTime = null; } /** @@ -1074,6 +1605,371 @@ class Client } } + /** + * Check if an exception represents a transient transaction error. + * + * @param Exception $exception Exception to check + * @return bool True if transient transaction error + */ + public function isTransientTransactionError(Exception $exception): bool + { + $message = $exception->getMessage(); + $code = $exception->getCode(); + + // MongoDB transient error codes + $transientCodes = [ + self::TRANSACTION_TIMEOUT_ERROR, + self::TRANSACTION_ABORTED_ERROR, + 6, // HostUnreachable + 7, // HostNotFound + 89, // NetworkTimeout + 91, // ShutdownInProgress + 189, // PrimarySteppedDown + 262, // ExceededTimeLimit + 9001, // SocketException + 10107, // NotMaster + 11600, // InterruptedAtShutdown + 11602, // InterruptedDueToReplStateChange + 13435, // NotMasterNoSlaveOk + 13436, // NotMasterOrSecondary + ]; + + return in_array($code, $transientCodes) || + str_contains($message, self::TRANSIENT_TRANSACTION_ERROR) || + str_contains($message, 'connection') || + str_contains($message, 'timeout') || + str_contains($message, 'network'); + } + + /** + * Check if an exception represents an unknown transaction commit result. + * + * @param Exception $exception Exception to check + * @return bool True if unknown commit result + */ + public function isUnknownTransactionCommitResult(Exception $exception): bool + { + $message = $exception->getMessage(); + $code = $exception->getCode(); + + $unknownCommitCodes = [ + self::TRANSACTION_TIMEOUT_ERROR, + 91, // ShutdownInProgress + 189, // PrimarySteppedDown + 262, // ExceededTimeLimit + 9001, // SocketException + 10107, // NotMaster + 11600, // InterruptedAtShutdown + 11602, // InterruptedDueToReplStateChange + 13435, // NotMasterNoSlaveOk + 13436, // NotMasterOrSecondary + ]; + + return in_array($code, $unknownCommitCodes) || + str_contains($message, self::UNKNOWN_TRANSACTION_COMMIT_RESULT); + } + + /** + * Execute a callback within a transaction with automatic retry logic. + * + * @param array $session Session from startSession() + * @param callable $callback Transaction callback that receives the session + * @param array $options Transaction options supporting: + * - readConcern: Read concern specification + * - writeConcern: Write concern specification + * - readPreference: Read preference + * - maxCommitTimeMS: Maximum time to allow for commit + * - maxRetries: Maximum number of retries (default: 3) + * - retryDelayMs: Delay between retries in milliseconds (default: 100) + * @return mixed Result from callback + * @throws Exception + */ + public function withTransaction(array $session, callable $callback, array $options = []) + { + $maxRetries = $options['maxRetries'] ?? 3; + $retryDelayMs = $options['retryDelayMs'] ?? 100; + $attempt = 0; + + while ($attempt <= $maxRetries) { + try { + // Start transaction + $this->startTransaction($session, $options); + + try { + // Execute user callback + $result = $callback($session); + + // Attempt to commit + $commitAttempt = 0; + $maxCommitRetries = 3; + + while ($commitAttempt <= $maxCommitRetries) { + try { + $this->commitTransaction($session, $options); + return $result; + } catch (Exception $e) { + if ($this->isUnknownTransactionCommitResult($e) && $commitAttempt < $maxCommitRetries) { + $commitAttempt++; + if ($retryDelayMs > 0) { + usleep($retryDelayMs * 1000); + } + continue; + } + throw $e; + } + } + } catch (Exception $e) { + // Abort transaction on any error in callback or commit + try { + $this->abortTransaction($session); + } catch (Exception $abortError) { + // Log abort error but don't mask original error + error_log("Error aborting transaction: " . $abortError->getMessage()); + } + throw $e; + } + } catch (Exception $e) { + if ($this->isTransientTransactionError($e) && $attempt < $maxRetries) { + $attempt++; + if ($retryDelayMs > 0) { + usleep($retryDelayMs * 1000); + } + continue; + } + throw $e; + } + } + + throw new Exception('Transaction failed after maximum retries'); + } + + /** + * Update causal consistency timestamps from operation results. + * + * @param mixed $result Operation result + */ + private function updateCausalConsistency($result): void + { + if (is_object($result)) { + if (property_exists($result, 'operationTime')) { + $this->operationTime = $result->operationTime; + } + if (property_exists($result, '$clusterTime')) { + $this->clusterTime = $result->{'$clusterTime'}; + } + } + } + + /** + * Get the current operation time for causal consistency. + * + * @return object|null Current operation time + */ + public function getOperationTime(): ?object + { + return $this->operationTime; + } + + /** + * Get the current cluster time for causal consistency. + * + * @return object|null Current cluster time + */ + public function getClusterTime(): ?object + { + return $this->clusterTime; + } + + /** + * Get session state information for debugging. + * + * @param array $session Session to inspect + * @return array Session state information + */ + public function getSessionState(array $session): array + { + $rawId = $session['sessionId'] ?? ($session['id']->id ?? null); + $sessionId = $rawId instanceof \MongoDB\BSON\Binary + ? bin2hex($rawId->getData()) + : $rawId; + + if (!$sessionId || !isset($this->sessions[$sessionId])) { + return ['error' => 'Session not found']; + } + + return [ + 'sessionId' => $sessionId, + 'state' => $this->sessions[$sessionId]['state'], + 'txnNumber' => $this->sessions[$sessionId]['txnNumber'], + 'lastUse' => $this->sessions[$sessionId]['lastUse'], + 'retryableWriteNumber' => $this->sessions[$sessionId]['retryableWriteNumber'] + ]; + } + + /** + * Validate connection before operation with comprehensive checks. + * + * @throws Exception If connection is invalid + */ + private function validateConnection(): void + { + if (!$this->isConnected) { + throw new Exception('Client is not connected to MongoDB'); + } + + if (!isset($this->client)) { + $this->isConnected = false; + throw new Exception('MongoDB client is not initialized'); + } + + if (!$this->client->isConnected()) { + $this->isConnected = false; + throw new Exception('Connection to MongoDB has been lost'); + } + } + + /** + * Create a write concern object with validation. + * + * @param array|string|int $writeConcern Write concern specification + * @return array Validated write concern + * @throws Exception If write concern is invalid + */ + public function createWriteConcern($writeConcern): array + { + if (is_string($writeConcern)) { + return ['w' => $writeConcern]; + } + + if (is_int($writeConcern)) { + if ($writeConcern < 0) { + throw new Exception('Write concern w value must be >= 0'); + } + return ['w' => $writeConcern]; + } + + if (is_array($writeConcern)) { + $concern = []; + + if (isset($writeConcern['w'])) { + if (is_int($writeConcern['w']) && $writeConcern['w'] < 0) { + throw new Exception('Write concern w value must be >= 0'); + } + $concern['w'] = $writeConcern['w']; + } + + if (isset($writeConcern['j'])) { + $concern['j'] = (bool)$writeConcern['j']; + } + + if (isset($writeConcern['wtimeout'])) { + if (!is_int($writeConcern['wtimeout']) || $writeConcern['wtimeout'] < 0) { + throw new Exception('Write concern wtimeout must be a non-negative integer'); + } + $concern['wtimeout'] = $writeConcern['wtimeout']; + } + + return $concern; + } + + throw new Exception('Invalid write concern format'); + } + + /** + * Create a read concern object with validation. + * + * @param array|string $readConcern Read concern specification + * @return array Validated read concern + * @throws Exception If read concern is invalid + */ + public function createReadConcern($readConcern): array + { + if (is_string($readConcern)) { + $validLevels = [ + self::READ_CONCERN_LOCAL, + self::READ_CONCERN_AVAILABLE, + self::READ_CONCERN_MAJORITY, + self::READ_CONCERN_LINEARIZABLE, + self::READ_CONCERN_SNAPSHOT + ]; + + if (!in_array($readConcern, $validLevels)) { + throw new Exception('Invalid read concern level: ' . $readConcern); + } + + return ['level' => $readConcern]; + } + + if (is_array($readConcern)) { + $concern = []; + + if (isset($readConcern['level'])) { + $validLevels = [ + self::READ_CONCERN_LOCAL, + self::READ_CONCERN_AVAILABLE, + self::READ_CONCERN_MAJORITY, + self::READ_CONCERN_LINEARIZABLE, + self::READ_CONCERN_SNAPSHOT + ]; + + if (!in_array($readConcern['level'], $validLevels)) { + throw new Exception('Invalid read concern level: ' . $readConcern['level']); + } + + $concern['level'] = $readConcern['level']; + } + + if (isset($readConcern['afterClusterTime'])) { + $concern['afterClusterTime'] = $readConcern['afterClusterTime']; + } + + return $concern; + } + + throw new Exception('Invalid read concern format'); + } + + /** + * Get connection status information. + * + * @return array Connection status details + */ + public function getConnectionInfo(): array + { + return [ + 'connected' => $this->isConnected, + 'host' => $this->host, + 'port' => $this->port, + 'database' => $this->database, + 'activeSessions' => count($this->sessions), + 'clusterTimeSet' => $this->clusterTime !== null, + 'operationTimeSet' => $this->operationTime !== null + ]; + } + + /** + * Clean up stale sessions (older than 30 minutes). + */ + public function cleanupStaleSessions(): void + { + $cutoff = time() - 1800; // 30 minutes + $staleSessions = []; + + foreach ($this->sessions as $sessionId => $sessionData) { + if ($sessionData['lastUse'] < $cutoff) { + $staleSessions[] = ['id' => $sessionData['id'], 'sessionId' => $sessionId]; + } + } + + if (!empty($staleSessions)) { + try { + $this->endSessions($staleSessions); + } catch (Exception $e) { + error_log("Error cleaning up stale sessions: " . $e->getMessage()); + } + } + } + /** * Destructor to ensure proper cleanup. */ diff --git a/tests/MongoTest.php b/tests/MongoTest.php index a755ae717b..11c0064628 100644 --- a/tests/MongoTest.php +++ b/tests/MongoTest.php @@ -13,6 +13,7 @@ class MongoTest extends TestCase /** * @throws Exception + * @throws \Exception */ public static function getDatabase(): Client { @@ -20,7 +21,15 @@ class MongoTest extends TestCase return self::$db; } - $client = new Client('testing', 'mongo', 27017, 'root', 'example', false); + $client = new Client( + database: 'testing', + host: 'mongo', + port: 27017, + user: 'root', + password: 'example', + useCoroutine: false + ); + $client->connect(); self::$db = $client; @@ -29,7 +38,7 @@ class MongoTest extends TestCase public function testDeleteDatabase() { - self::assertTrue($this->getDatabase()->dropDatabase([])); + self::assertTrue($this->getDatabase()->dropDatabase()); } diff --git a/tests/TransactionTest.php b/tests/TransactionTest.php new file mode 100644 index 0000000000..1ae76431d2 --- /dev/null +++ b/tests/TransactionTest.php @@ -0,0 +1,424 @@ +connect(); + } catch (Exception $e) { + self::markTestSkipped('MongoDB connection failed: ' . $e->getMessage()); + } + } + + public static function tearDownAfterClass(): void + { + self::$client?->close(); + } + + private function getClient(): Client + { + if (!self::$client) { + self::markTestSkipped('MongoDB client not available'); + } + return self::$client; + } + + /** + * Check if MongoDB instance supports transactions (requires replica set) + */ + private function isReplicatSet(): bool + { + try { + $client = $this->getClient(); + + // Try to get server status to check if it's a replica set + $result = $client->query(['isMaster' => 1], 'admin'); + + // Check various fields that indicate replica set or sharding + $isReplicaSet = isset($result->setName) || + isset($result->hosts) || + isset($result->ismaster) && isset($result->secondary) || + isset($result->isWritablePrimary) || + isset($result->msg) && $result->msg === 'isdbgrid'; + + if (!$isReplicaSet) { + return false; + } + } catch (\Exception $e) { + try { + $client = $this->getClient(); + $testSession = $client->startSession(); + $client->startTransaction($testSession); + + // Try a simple insert with transaction params + $client->insert( + '_test_tx_check', + ['test' => true], + ['session' => $testSession] + ); + + // If we get here, transactions work - abort and clean up + $client->abortTransaction($testSession); + $client->endSessions([$testSession]); + $client->delete('_test_tx_check', ['test' => true]); + } catch (Exception $txError) { + if (strpos($txError->getMessage(), 'Transaction numbers are only allowed') !== false || + strpos($txError->getMessage(), 'IllegalOperation') !== false) { + return false; + } + } + } + + return true; + } + + /** + * Test basic session creation and cleanup + */ + public function testSessionManagement() + { + $client = $this->getClient(); + + // Create session with options + $session = $client->startSession([ + 'causalConsistency' => true, + 'defaultTransactionOptions' => [ + 'readConcern' => ['level' => 'majority'], + 'writeConcern' => ['w' => 1, 'j' => true] + ] + ]); + + $this->assertArrayHasKey('id', $session); + $this->assertArrayHasKey('sessionId', $session); + + // Get session state + $state = $client->getSessionState($session); + $this->assertEquals('none', $state['state']); + $this->assertEquals(0, $state['txnNumber']); + + // End session + $client->endSessions([$session]); + + // Verify session is cleaned up + $stateAfterEnd = $client->getSessionState($session); + $this->assertArrayHasKey('error', $stateAfterEnd); + } + + /** + * Test transaction with proper state management + */ + public function testTransactionStateManagement() + { + if (!$this->isReplicatSet()) { + $this->expectNotToPerformAssertions(); + return; + } + + $client = $this->getClient(); + $session = $client->startSession(); + + try { + // Start transaction + $result = $client->startTransaction($session, [ + 'readConcern' => ['level' => 'majority'], + 'writeConcern' => ['w' => 1] + ]); + + $this->assertTrue($result); + + // Verify transaction state + $state = $client->getSessionState($session); + $this->assertEquals('in_progress', $state['state']); + $this->assertEquals(1, $state['txnNumber']); + + // Perform operations within transaction + $client->insert( + 'test_collection', + ['name' => 'test_doc', 'value' => 42], + ['session' => $session] + ); + + // Commit transaction + $commitResult = $client->commitTransaction($session); + $this->assertNotNull($commitResult); + + // Verify final state + $finalState = $client->getSessionState($session); + $this->assertEquals('committed', $finalState['state']); + + } finally { + $client->endSessions([$session]); + } + } + + /** + * Test transaction abort functionality + */ + public function testTransactionAbort() + { + if (!$this->isReplicatSet()) { + $this->expectNotToPerformAssertions(); + return; + } + + $client = $this->getClient(); + $session = $client->startSession(); + + try { + $client->startTransaction($session); + + // Insert a document + $client->insert( + 'test_collection', + ['name' => 'abort_test', 'value' => 999], + ['session' => $session] + ); + + // Abort transaction + $abortResult = $client->abortTransaction($session); + $this->assertNotNull($abortResult); + + // Verify transaction was aborted + $state = $client->getSessionState($session); + $this->assertEquals('aborted', $state['state']); + + // Verify document was not inserted (transaction rolled back) + $found = $client->find('test_collection', ['name' => 'abort_test']); + $this->assertEmpty($found->cursor->firstBatch); + + } finally { + $client->endSessions([$session]); + } + } + + /** + * Test withTransaction helper with retry logic + */ + public function testWithTransactionHelper() + { + if (!$this->isReplicatSet()) { + $this->expectNotToPerformAssertions(); + return; + } + + $client = $this->getClient(); + $session = $client->startSession(); + + try { + $result = $client->withTransaction($session, function ($session) use ($client) { + // Insert multiple documents in transaction + $client->insert( + 'test_collection', + ['name' => 'with_transaction_1', 'counter' => 1], + ['session' => $session] + ); + + $client->insert( + 'test_collection', + ['name' => 'with_transaction_2', 'counter' => 2], + ['session' => $session] + ); + + return 'transaction_completed'; + }, [ + 'readConcern' => ['level' => 'majority'], + 'writeConcern' => ['w' => 1], + 'maxRetries' => 3 + ]); + + $this->assertEquals('transaction_completed', $result); + + // Verify both documents were inserted + $found1 = $client->find('test_collection', ['name' => 'with_transaction_1']); + $found2 = $client->find('test_collection', ['name' => 'with_transaction_2']); + + $this->assertNotEmpty($found1->cursor->firstBatch); + $this->assertNotEmpty($found2->cursor->firstBatch); + + } finally { + $client->endSessions([$session]); + } + } + + /** + * Test read and write concerns validation + */ + public function testReadWriteConcerns() + { + $client = $this->getClient(); + + // Test valid write concern + $writeConcern = $client->createWriteConcern(['w' => 'majority', 'j' => true, 'wtimeout' => 5000]); + $this->assertEquals('majority', $writeConcern['w']); + $this->assertTrue($writeConcern['j']); + $this->assertEquals(5000, $writeConcern['wtimeout']); + + // Test valid read concern + $readConcern = $client->createReadConcern(['level' => 'majority']); + $this->assertEquals('majority', $readConcern['level']); + + // Test invalid read concern should throw exception + $this->expectException(Exception::class); + $client->createReadConcern(['level' => 'invalid']); + } + + /** + * Test CRUD operations with session and concerns + */ + public function testCRUDWithSessionAndConcerns() + { + if (!$this->isReplicatSet()) { + $this->expectNotToPerformAssertions(); + return; + } + + $client = $this->getClient(); + $session = $client->startSession(); + + try { + $client->startTransaction($session); + + // Insert with session and write concern + $insertedDoc = $client->insert( + 'test_collection', + ['name' => 'crud_test', 'status' => 'active'], + [ + 'session' => $session, + 'writeConcern' => ['w' => 1, 'j' => true] + ] + ); + + $this->assertArrayHasKey('_id', $insertedDoc); + + // Find with session and read concern + $found = $client->find( + 'test_collection', + ['name' => 'crud_test'], + [ + 'session' => $session, + 'readConcern' => ['level' => 'local'] + ] + ); + + $this->assertNotEmpty($found->cursor->firstBatch); + + // Update with session + $client->update( + 'test_collection', + ['name' => 'crud_test'], + ['$set' => ['status' => 'updated']], + [ + 'session' => $session, + 'writeConcern' => ['w' => 1] + ] + ); + + // Count with session + $count = $client->count( + 'test_collection', + ['name' => 'crud_test'], + [ + 'session' => $session, + 'readConcern' => ['level' => 'local'] + ] + ); + + $this->assertEquals(1, $count); + + $client->commitTransaction($session); + + } finally { + $client->endSessions([$session]); + } + } + + /** + * Test connection validation and health checks + */ + public function testConnectionValidation() + { + $client = $this->getClient(); + + // Get connection info + $info = $client->getConnectionInfo(); + + $this->assertTrue($info['connected']); + $this->assertEquals('mongo', $info['host']); + $this->assertEquals(27017, $info['port']); + $this->assertEquals('testing', $info['database']); + $this->assertIsInt($info['activeSessions']); + } + + /** + * Test causal consistency tracking + */ + public function testCausalConsistency() + { + $client = $this->getClient(); + + // Perform an operation to get operation time + $client->find('test_collection', []); + + // Check if operation time is tracked + $operationTime = $client->getOperationTime(); + $clusterTime = $client->getClusterTime(); + + // These may be null if not in a replica set, which is fine for testing + $this->assertTrue($operationTime === null || is_object($operationTime)); + $this->assertTrue($clusterTime === null || is_object($clusterTime)); + } + + /** + * Test session cleanup + */ + public function testSessionCleanup() + { + $client = $this->getClient(); + + // Create multiple sessions + $sessions = []; + for ($i = 0; $i < 3; $i++) { + $sessions[] = $client->startSession(); + } + + // Verify sessions are active + $info = $client->getConnectionInfo(); + $this->assertGreaterThanOrEqual(3, $info['activeSessions']); + + // End all sessions + $client->endSessions($sessions); + + // Verify sessions are cleaned up + $infoAfter = $client->getConnectionInfo(); + $this->assertLessThan($info['activeSessions'], $infoAfter['activeSessions']); + } + + protected function tearDown(): void + { + // Clean up test data + if (self::$client) { + try { + self::$client->dropCollection('test_collection'); + } catch (Exception $e) { + // Ignore cleanup errors + } + } + } +}