PHPC-1140: Implement Transactions specification

Author: derickr

.travis.yml

@@ -32,6 +32,9 @@ matrix:
     - php: 7.0
       env:
         - SERVER_VERSION=3.4.11
+    - php: 7.0
+      env:
+        - SERVER_VERSION=4.0.0-rc4
 
 before_install:
   - pip install "mongo-orchestration>=0.6.7,<1.0" --user `whoami`

php_phongo.c

@@ -180,11 +180,39 @@ void phongo_throw_exception(php_phongo_error_domain_t domain TSRMLS_DC, const ch
 	efree(message);
 	va_end(args);
 }
+
 void phongo_throw_exception_from_bson_error_t(bson_error_t* error TSRMLS_DC)
 {
 	zend_throw_exception(phongo_exception_from_mongoc_domain(error->domain, error->code), error->message, error->code TSRMLS_CC);
 }
 
+void phongo_throw_exception_from_bson_error_and_reply_t(bson_error_t* error, bson_t* reply TSRMLS_DC)
+{
+	/* Server errors (other than ExceededTimeLimit) and write concern errors
+	 * may use CommandException and report the result document for the
+	 * failed command. For BC, ExceededTimeLimit errors will continue to use
+	 * ExcecutionTimeoutException and omit the result document. */
+	if ((error->domain == MONGOC_ERROR_SERVER && error->code != PHONGO_SERVER_ERROR_EXCEEDED_TIME_LIMIT) || error->domain == MONGOC_ERROR_WRITE_CONCERN) {
+#if PHP_VERSION_ID >= 70000
+		zval zv;
+#else
+		zval* zv;
+#endif
+
+		zend_throw_exception(php_phongo_commandexception_ce, error->message, error->code TSRMLS_CC);
+		php_phongo_bson_to_zval(bson_get_data(reply), reply->len, &zv);
+
+#if PHP_VERSION_ID >= 70000
+		phongo_add_exception_prop(ZEND_STRL("resultDocument"), &zv);
+#else
+		phongo_add_exception_prop(ZEND_STRL("resultDocument"), zv TSRMLS_CC);
+#endif
+		zval_ptr_dtor(&zv);
+	} else {
+		phongo_throw_exception_from_bson_error_t(error TSRMLS_CC);
+	}
+}
+
 static void php_phongo_log(mongoc_log_level_t log_level, const char* log_domain, const char* message, void* user_data)
 {
 	struct timeval tv;
@@ -927,29 +955,7 @@ bool phongo_execute_command(mongoc_client_t* client, php_phongo_command_type_t t
 	free_reply = true;
 
 	if (!result) {
-		/* Server errors (other than ExceededTimeLimit) and write concern errors
-		 * may use CommandException and report the result document for the
-		 * failed command. For BC, ExceededTimeLimit errors will continue to use
-		 * ExcecutionTimeoutException and omit the result document. */
-		if ((error.domain == MONGOC_ERROR_SERVER && error.code != PHONGO_SERVER_ERROR_EXCEEDED_TIME_LIMIT) || error.domain == MONGOC_ERROR_WRITE_CONCERN) {
-#if PHP_VERSION_ID >= 70000
-			zval zv;
-#else
-			zval* zv;
-#endif
-
-			zend_throw_exception(php_phongo_commandexception_ce, error.message, error.code TSRMLS_CC);
-			php_phongo_bson_to_zval(bson_get_data(&reply), reply.len, &zv);
-
-#if PHP_VERSION_ID >= 70000
-			phongo_add_exception_prop(ZEND_STRL("resultDocument"), &zv);
-#else
-			phongo_add_exception_prop(ZEND_STRL("resultDocument"), zv TSRMLS_CC);
-#endif
-			zval_ptr_dtor(&zv);
-		} else {
-			phongo_throw_exception_from_bson_error_t(&error TSRMLS_CC);
-		}
+		phongo_throw_exception_from_bson_error_and_reply_t(&error, &reply TSRMLS_CC);
 		goto cleanup;
 	}
 

php_phongo.h

@@ -111,6 +111,7 @@ void              phongo_throw_exception(php_phongo_error_domain_t domain TSRMLS
 #endif /* PHP_VERSION_ID < 70000 */
 	;
 void phongo_throw_exception_from_bson_error_t(bson_error_t* error TSRMLS_DC);
+void phongo_throw_exception_from_bson_error_and_reply_t(bson_error_t* error, bson_t* reply TSRMLS_DC);
 
 /* This enum is used for processing options in phongo_execute_parse_options and
  * selecting a libmongoc function to use in phongo_execute_command. The values

scripts/presets/standalone-30.json

@@ -8,7 +8,7 @@
         "logpath": "/tmp/standalone-30/mongod.log",
         "journal": true,
         "port": 2700,
-        "bind_ip_all": true,
+        "bind_ip": "0.0.0.0,::",
         "setParameter": {"enableTestCommands": 1}
     },
     "version": "30-release"

src/MongoDB/Manager.c

@@ -26,6 +26,7 @@
 #include "php_array_api.h"
 #include "phongo_compat.h"
 #include "php_phongo.h"
+#include "Session.h"
 
 #define PHONGO_MANAGER_URI_DEFAULT "mongodb://127.0.0.1/"
 
@@ -655,11 +656,12 @@ static PHP_METHOD(Manager, selectServer)
    Returns a new client session */
 static PHP_METHOD(Manager, startSession)
 {
-	php_phongo_manager_t*    intern;
-	zval*                    options = NULL;
-	mongoc_session_opt_t*    cs_opts = NULL;
-	mongoc_client_session_t* cs;
-	bson_error_t             error = { 0 };
+	php_phongo_manager_t*     intern;
+	zval*                     options = NULL;
+	mongoc_session_opt_t*     cs_opts = NULL;
+	mongoc_client_session_t*  cs;
+	bson_error_t              error    = { 0 };
+	mongoc_transaction_opt_t* txn_opts = NULL;
 	SUPPRESS_UNUSED_WARNING(return_value_ptr)
 	SUPPRESS_UNUSED_WARNING(return_value_used)
 
@@ -674,17 +676,51 @@ static PHP_METHOD(Manager, startSession)
 		mongoc_session_opts_set_causal_consistency(cs_opts, php_array_fetchc_bool(options, "causalConsistency"));
 	}
 
-	cs = mongoc_client_start_session(intern->client, cs_opts, &error);
+	if (options && php_array_existsc(options, "defaultTransactionOptions")) {
+		zval* txn_options = php_array_fetchc(options, "defaultTransactionOptions");
 
-	if (cs_opts) {
-		mongoc_session_opts_destroy(cs_opts);
+		/* Thrown exception and return if the defaultTransactionOptions is not an array */
+		if (Z_TYPE_P(txn_options) != IS_ARRAY) {
+			phongo_throw_exception(
+				PHONGO_ERROR_INVALID_ARGUMENT TSRMLS_CC,
+				"Expected \"defaultTransactionOptions\" option to be an array, %s given",
+				PHONGO_ZVAL_CLASS_OR_TYPE_NAME_P(txn_options)
+			);
+			goto cleanup;
+		}
+
+		/* Parse transaction options */
+		txn_opts = php_mongodb_session_parse_transaction_options(txn_options TSRMLS_CC);
+
+		/* If an exception is thrown while parsing, the txn_opts struct is also
+		 * NULL, so no need to free it here */
+		if (EG(exception)) {
+			goto cleanup;
+		}
+
+		/* If the options are non-empty, add them to the client session opts struct */
+		if (txn_opts) {
+			if (!cs_opts) {
+				cs_opts = mongoc_session_opts_new();
+			}
+
+			mongoc_session_opts_set_default_transaction_opts(cs_opts, txn_opts);
+			mongoc_transaction_opts_destroy(txn_opts);
+		}
 	}
 
+	cs = mongoc_client_start_session(intern->client, cs_opts, &error);
+
 	if (cs) {
 		phongo_session_init(return_value, cs TSRMLS_CC);
 	} else {
 		phongo_throw_exception_from_bson_error_t(&error TSRMLS_CC);
 	}
+
+cleanup:
+	if (cs_opts) {
+		mongoc_session_opts_destroy(cs_opts);
+	}
 } /* }}} */
 
 /* {{{ MongoDB\Driver\Manager function entries */

src/MongoDB/Session.c

@@ -24,6 +24,8 @@
 #include "phongo_compat.h"
 #include "php_phongo.h"
 #include "php_bson.h"
+#include "php_array_api.h"
+#include "Session.h"
 
 zend_class_entry* php_phongo_session_ce;
 
@@ -228,6 +230,166 @@ static PHP_METHOD(Session, getOperationTime)
 	php_phongo_new_timestamp_from_increment_and_timestamp(return_value, increment, timestamp TSRMLS_CC);
 } /* }}} */
 
+/* Creates a opts structure from an array optionally containing an RP, RC,
+ * and/or WC object. Returns NULL if no options were found, or there was an
+ * invalid option. If there was an invalid option or structure, an exception
+ * will be thrown too. */
+mongoc_transaction_opt_t* php_mongodb_session_parse_transaction_options(zval* options TSRMLS_DC)
+{
+	mongoc_transaction_opt_t* opts = NULL;
+
+	if (php_array_existsc(options, "readConcern")) {
+		zval* read_concern = php_array_fetchc(options, "readConcern");
+
+		if (Z_TYPE_P(read_concern) != IS_OBJECT || !instanceof_function(Z_OBJCE_P(read_concern), php_phongo_readconcern_ce TSRMLS_CC)) {
+			phongo_throw_exception(PHONGO_ERROR_INVALID_ARGUMENT TSRMLS_CC, "Expected \"readConcern\" option to be %s, %s given", ZSTR_VAL(php_phongo_readconcern_ce->name), PHONGO_ZVAL_CLASS_OR_TYPE_NAME_P(read_concern));
+			/* Freeing opts is not needed here, as it can't be set yet. The
+			 * code is here to keep it consistent with the others in case more
+			 * options are added before this one. */
+			if (opts) {
+				mongoc_transaction_opts_destroy(opts);
+			}
+			return NULL;
+		}
+
+		if (!opts) {
+			opts = mongoc_transaction_opts_new();
+		}
+
+		mongoc_transaction_opts_set_read_concern(opts, phongo_read_concern_from_zval(read_concern TSRMLS_CC));
+	}
+
+	if (php_array_existsc(options, "readPreference")) {
+		zval* read_preference = php_array_fetchc(options, "readPreference");
+
+		if (Z_TYPE_P(read_preference) != IS_OBJECT || !instanceof_function(Z_OBJCE_P(read_preference), php_phongo_readpreference_ce TSRMLS_CC)) {
+			phongo_throw_exception(PHONGO_ERROR_INVALID_ARGUMENT TSRMLS_CC, "Expected \"readPreference\" option to be %s, %s given", ZSTR_VAL(php_phongo_readpreference_ce->name), PHONGO_ZVAL_CLASS_OR_TYPE_NAME_P(read_preference));
+			if (opts) {
+				mongoc_transaction_opts_destroy(opts);
+			}
+			return NULL;
+		}
+
+		if (!opts) {
+			opts = mongoc_transaction_opts_new();
+		}
+
+		mongoc_transaction_opts_set_read_prefs(opts, phongo_read_preference_from_zval(read_preference TSRMLS_CC));
+	}
+
+	if (php_array_existsc(options, "writeConcern")) {
+		zval* write_concern = php_array_fetchc(options, "writeConcern");
+
+		if (Z_TYPE_P(write_concern) != IS_OBJECT || !instanceof_function(Z_OBJCE_P(write_concern), php_phongo_writeconcern_ce TSRMLS_CC)) {
+			phongo_throw_exception(PHONGO_ERROR_INVALID_ARGUMENT TSRMLS_CC, "Expected \"writeConcern\" option to be %s, %s given", ZSTR_VAL(php_phongo_writeconcern_ce->name), PHONGO_ZVAL_CLASS_OR_TYPE_NAME_P(write_concern));
+			if (opts) {
+				mongoc_transaction_opts_destroy(opts);
+			}
+			return NULL;
+		}
+
+		if (!opts) {
+			opts = mongoc_transaction_opts_new();
+		}
+
+		mongoc_transaction_opts_set_write_concern(opts, phongo_write_concern_from_zval(write_concern TSRMLS_CC));
+	}
+
+	return opts;
+}
+
+/* {{{ proto void MongoDB\Driver\Session::startTransaction([array $options = null])
+   Starts a new transaction */
+static PHP_METHOD(Session, startTransaction)
+{
+	php_phongo_session_t*     intern;
+	zval*                     options     = NULL;
+	mongoc_transaction_opt_t* txn_options = NULL;
+	bson_error_t              error;
+	SUPPRESS_UNUSED_WARNING(return_value_ptr)
+	SUPPRESS_UNUSED_WARNING(return_value_used)
+
+	intern = Z_SESSION_OBJ_P(getThis());
+
+	if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "|a", &options) == FAILURE) {
+		return;
+	}
+
+	if (options) {
+		txn_options = php_mongodb_session_parse_transaction_options(options TSRMLS_CC);
+	}
+	if (EG(exception)) {
+		return;
+	}
+
+	if (!mongoc_client_session_start_transaction(intern->client_session, txn_options, &error)) {
+		phongo_throw_exception_from_bson_error_t(&error TSRMLS_CC);
+	}
+
+	if (txn_options) {
+		mongoc_transaction_opts_destroy(txn_options);
+	}
+} /* }}} */
+
+/* {{{ proto void MongoDB\Driver\Session::commitTransaction(void)
+   Commits an existing transaction */
+static PHP_METHOD(Session, commitTransaction)
+{
+	php_phongo_session_t* intern;
+	bson_error_t          error;
+	bson_t                reply;
+	SUPPRESS_UNUSED_WARNING(return_value_ptr)
+	SUPPRESS_UNUSED_WARNING(return_value_used)
+
+	intern = Z_SESSION_OBJ_P(getThis());
+
+	if (zend_parse_parameters_none() == FAILURE) {
+		return;
+	}
+
+	if (!mongoc_client_session_commit_transaction(intern->client_session, &reply, &error)) {
+		phongo_throw_exception_from_bson_error_and_reply_t(&error, &reply TSRMLS_CC);
+		bson_destroy(&reply);
+	}
+} /* }}} */
+
+/* {{{ proto void MongoDB\Driver\Session::abortTransaction(void)
+   Aborts (rolls back) an existing transaction */
+static PHP_METHOD(Session, abortTransaction)
+{
+	php_phongo_session_t* intern;
+	bson_error_t          error;
+	SUPPRESS_UNUSED_WARNING(return_value_ptr)
+	SUPPRESS_UNUSED_WARNING(return_value_used)
+
+	intern = Z_SESSION_OBJ_P(getThis());
+
+	if (zend_parse_parameters_none() == FAILURE) {
+		return;
+	}
+
+	if (!mongoc_client_session_abort_transaction(intern->client_session, &error)) {
+		phongo_throw_exception_from_bson_error_t(&error TSRMLS_CC);
+	}
+} /* }}} */
+
+/* {{{ proto void MongoDB\Driver\Session::endSession(void)
+   Ends the session, and a running transaction if active */
+static PHP_METHOD(Session, endSession)
+{
+	php_phongo_session_t* intern;
+	SUPPRESS_UNUSED_WARNING(return_value_ptr)
+	SUPPRESS_UNUSED_WARNING(return_value_used)
+
+	intern = Z_SESSION_OBJ_P(getThis());
+
+	if (zend_parse_parameters_none() == FAILURE) {
+		return;
+	}
+
+	mongoc_client_session_destroy(intern->client_session);
+} /* }}} */
+
 /* {{{ MongoDB\Driver\Session function entries */
 ZEND_BEGIN_ARG_INFO_EX(ai_Session_advanceClusterTime, 0, 0, 1)
 	ZEND_ARG_INFO(0, clusterTime)
@@ -237,6 +399,10 @@ ZEND_BEGIN_ARG_INFO_EX(ai_Session_advanceOperationTime, 0, 0, 1)
 	ZEND_ARG_INFO(0, timestamp)
 ZEND_END_ARG_INFO()
 
+ZEND_BEGIN_ARG_INFO_EX(ai_Session_startTransaction, 0, 0, 0)
+	ZEND_ARG_INFO(0, options)
+ZEND_END_ARG_INFO()
+
 ZEND_BEGIN_ARG_INFO_EX(ai_Session_void, 0, 0, 0)
 ZEND_END_ARG_INFO()
 
@@ -247,6 +413,10 @@ static zend_function_entry php_phongo_session_me[] = {
 	PHP_ME(Session, getClusterTime, ai_Session_void, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
 	PHP_ME(Session, getLogicalSessionId, ai_Session_void, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
 	PHP_ME(Session, getOperationTime, ai_Session_void, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
+	PHP_ME(Session, startTransaction, ai_Session_startTransaction, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
+	PHP_ME(Session, commitTransaction, ai_Session_void, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
+	PHP_ME(Session, abortTransaction, ai_Session_void, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
+	PHP_ME(Session, endSession, ai_Session_void, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
 	ZEND_NAMED_ME(__construct, PHP_FN(MongoDB_disabled___construct), ai_Session_void, ZEND_ACC_PRIVATE | ZEND_ACC_FINAL)
 	ZEND_NAMED_ME(__wakeup, PHP_FN(MongoDB_disabled___wakeup), ai_Session_void, ZEND_ACC_PUBLIC | ZEND_ACC_FINAL)
 	PHP_FE_END

src/MongoDB/Session.h

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2017 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.
+ */
+
+#ifndef PHP_MONGODB_DRIVER_SESSION_H
+#define PHP_MONGODB_DRIVER_SESSION_H
+
+mongoc_transaction_opt_t* php_mongodb_session_parse_transaction_options(zval* txnOptions TSRMLS_DC);
+
+#endif /* PHP_MONGODB_DRIVER_SESSION_H */