PHPC-980: MongoDB\Driver\Session and "session" option

This introduces a Session class, which wraps libmongoc's client session object. Additionally, we support a "session" option on Manager and Server execute methods to allow operations to be associated with an explicit session (mostly relevant for causal consistency).

Author: jmikola

config.m4

@@ -190,6 +190,7 @@ if test "$MONGODB" != "no"; then
     src/MongoDB/ReadConcern.c \
     src/MongoDB/ReadPreference.c \
     src/MongoDB/Server.c \
+    src/MongoDB/Session.c \
     src/MongoDB/WriteConcern.c \
     src/MongoDB/WriteConcernError.c \
     src/MongoDB/WriteError.c \

config.w32

@@ -85,7 +85,7 @@ if (PHP_MONGODB != "no") {
   EXTENSION("mongodb", "php_phongo.c phongo_compat.c", null, PHP_MONGODB_CFLAGS);
   ADD_SOURCES(configure_module_dirname + "/src", "bson.c bson-encode.c", "mongodb");
   ADD_SOURCES(configure_module_dirname + "/src/BSON", "Binary.c BinaryInterface.c DBPointer.c Decimal128.c Decimal128Interface.c Javascript.c JavascriptInterface.c MaxKey.c MaxKeyInterface.c MinKey.c MinKeyInterface.c ObjectId.c ObjectIdInterface.c Persistable.c Regex.c RegexInterface.c Serializable.c Symbol.c Timestamp.c TimestampInterface.c Type.c Undefined.c Unserializable.c UTCDateTime.c UTCDateTimeInterface.c functions.c", "mongodb");
-  ADD_SOURCES(configure_module_dirname + "/src/MongoDB", "BulkWrite.c Command.c Cursor.c CursorId.c Manager.c Query.c ReadConcern.c ReadPreference.c Server.c WriteConcern.c WriteConcernError.c WriteError.c WriteResult.c", "mongodb");
+  ADD_SOURCES(configure_module_dirname + "/src/MongoDB", "BulkWrite.c Command.c Cursor.c CursorId.c Manager.c Query.c ReadConcern.c ReadPreference.c Server.c Session.c WriteConcern.c WriteConcernError.c WriteError.c WriteResult.c", "mongodb");
   ADD_SOURCES(configure_module_dirname + "/src/MongoDB/Exception", "AuthenticationException.c BulkWriteException.c ConnectionException.c ConnectionTimeoutException.c Exception.c ExecutionTimeoutException.c InvalidArgumentException.c LogicException.c RuntimeException.c SSLConnectionException.c UnexpectedValueException.c WriteException.c", "mongodb");
   ADD_SOURCES(configure_module_dirname + "/src/MongoDB/Monitoring", "CommandFailedEvent.c CommandStartedEvent.c CommandSubscriber.c CommandSucceededEvent.c Subscriber.c functions.c", "mongodb");
   ADD_SOURCES(configure_module_dirname + "/src/libbson/src/bson", PHP_MONGODB_BSON_SOURCES, "mongodb");

php_phongo.c

@@ -306,6 +306,17 @@ void phongo_server_init(zval *return_value, mongoc_client_t *client, int server_
 }
 /* }}} */
 
+void phongo_session_init(zval *return_value, mongoc_client_session_t *client_session TSRMLS_DC) /* {{{ */
+{
+	php_phongo_session_t *session;
+
+	object_init_ex(return_value, php_phongo_session_ce);
+
+	session = Z_SESSION_OBJ_P(return_value);
+	session->client_session = client_session;
+}
+/* }}} */
+
 void phongo_readconcern_init(zval *return_value, const mongoc_read_concern_t *read_concern TSRMLS_DC) /* {{{ */
 {
 	php_phongo_readconcern_t *intern;
@@ -527,6 +538,25 @@ static bool process_read_preference(zval *option, bson_t *mongoc_opts, zval **zr
 	return true;
 }
 
+static bool process_session(zval *option, bson_t *mongoc_opts TSRMLS_DC)
+{
+	const mongoc_client_session_t *client_session;
+
+	if (Z_TYPE_P(option) != IS_OBJECT || !instanceof_function(Z_OBJCE_P(option), php_phongo_session_ce TSRMLS_CC)) {
+		phongo_throw_exception(PHONGO_ERROR_INVALID_ARGUMENT TSRMLS_CC, "Expected \"session\" option to be %s, %s given", ZSTR_VAL(php_phongo_session_ce->name), PHONGO_ZVAL_CLASS_OR_TYPE_NAME_P(option));
+		return false;
+	}
+
+	client_session = Z_SESSION_OBJ_P(option)->client_session;
+
+	if (!mongoc_client_session_append(Z_SESSION_OBJ_P(option)->client_session, mongoc_opts, NULL)) {
+		phongo_throw_exception(PHONGO_ERROR_INVALID_ARGUMENT TSRMLS_CC, "Error appending \"session\" option");
+		return false;
+	}
+
+	return true;
+}
+
 static bool process_write_concern(zval *option, bson_t *mongoc_opts, zval **zwriteConcern TSRMLS_DC)
 {
 	if (Z_TYPE_P(option) == IS_OBJECT && instanceof_function(Z_OBJCE_P(option), php_phongo_writeconcern_ce TSRMLS_CC)) {
@@ -573,6 +603,10 @@ static int phongo_execute_parse_options(mongoc_client_t* client, int server_id,
 				if (!process_read_preference(driver_option, mongoc_opts, zreadPreference, client, server_id)) {
 					return false;
 				}
+			} else if ((!strcmp(ZSTR_VAL(string_key), "session"))) {
+				if (!process_session(driver_option, mongoc_opts)) {
+					return false;
+				}
 			} else if ((!strcasecmp(ZSTR_VAL(string_key), "writeConcern")) && (type & PHONGO_COMMAND_WRITE)) {
 				if (!process_write_concern(driver_option, mongoc_opts, zwriteConcern)) {
 					return false;
@@ -606,6 +640,10 @@ static int phongo_execute_parse_options(mongoc_client_t* client, int server_id,
 				if (!process_read_preference(*driver_option, mongoc_opts, zreadPreference, client, server_id TSRMLS_CC)) {
 					return false;
 				}
+			} else if ((!strcmp(ZSTR_VAL(string_key), "session"))) {
+				if (!process_session(*driver_option, mongoc_opts)) {
+					return false;
+				}
 			} else if ((!strcasecmp(string_key, "writeConcern")) && (type & PHONGO_COMMAND_WRITE)) {
 				if (!process_write_concern(*driver_option, mongoc_opts, zwriteConcern TSRMLS_CC)) {
 					return false;
@@ -2693,6 +2731,7 @@ PHP_MINIT_FUNCTION(mongodb)
 	php_phongo_readconcern_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_readpreference_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_server_init_ce(INIT_FUNC_ARGS_PASSTHRU);
+	php_phongo_session_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_writeconcern_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_writeconcernerror_init_ce(INIT_FUNC_ARGS_PASSTHRU);
 	php_phongo_writeerror_init_ce(INIT_FUNC_ARGS_PASSTHRU);

php_phongo.h

@@ -126,6 +126,7 @@ typedef enum {
 zend_object_handlers *phongo_get_std_object_handlers(void);
 
 void                     phongo_server_init          (zval *return_value, mongoc_client_t *client, int server_id TSRMLS_DC);
+void                     phongo_session_init         (zval *return_value, mongoc_client_session_t *client_session TSRMLS_DC);
 void                     phongo_readconcern_init     (zval *return_value, const mongoc_read_concern_t *read_concern TSRMLS_DC);
 void                     phongo_readpreference_init  (zval *return_value, const mongoc_read_prefs_t *read_prefs TSRMLS_DC);
 void                     phongo_writeconcern_init    (zval *return_value, const mongoc_write_concern_t *write_concern TSRMLS_DC);

php_phongo_classes.h

@@ -52,6 +52,9 @@ static inline php_phongo_readpreference_t* php_readpreference_fetch_object(zend_
 static inline php_phongo_server_t* php_server_fetch_object(zend_object *obj) {
     return (php_phongo_server_t *)((char *)obj - XtOffsetOf(php_phongo_server_t, std));
 }
+static inline php_phongo_session_t* php_session_fetch_object(zend_object *obj) {
+    return (php_phongo_session_t *)((char *)obj - XtOffsetOf(php_phongo_session_t, std));
+}
 static inline php_phongo_writeconcern_t* php_writeconcern_fetch_object(zend_object *obj) {
     return (php_phongo_writeconcern_t *)((char *)obj - XtOffsetOf(php_phongo_writeconcern_t, std));
 }
@@ -118,6 +121,7 @@ static inline php_phongo_commandsucceededevent_t* php_commandsucceededevent_fetc
 # define Z_READCONCERN_OBJ_P(zv)       (php_readconcern_fetch_object(Z_OBJ_P(zv)))
 # define Z_READPREFERENCE_OBJ_P(zv)    (php_readpreference_fetch_object(Z_OBJ_P(zv)))
 # define Z_SERVER_OBJ_P(zv)            (php_server_fetch_object(Z_OBJ_P(zv)))
+# define Z_SESSION_OBJ_P(zv)           (php_session_fetch_object(Z_OBJ_P(zv)))
 # define Z_BULKWRITE_OBJ_P(zv)         (php_bulkwrite_fetch_object(Z_OBJ_P(zv)))
 # define Z_WRITECONCERN_OBJ_P(zv)      (php_writeconcern_fetch_object(Z_OBJ_P(zv)))
 # define Z_WRITECONCERNERROR_OBJ_P(zv) (php_writeconcernerror_fetch_object(Z_OBJ_P(zv)))
@@ -147,6 +151,7 @@ static inline php_phongo_commandsucceededevent_t* php_commandsucceededevent_fetc
 # define Z_OBJ_READCONCERN(zo)         (php_readconcern_fetch_object(zo))
 # define Z_OBJ_READPREFERENCE(zo)      (php_readpreference_fetch_object(zo))
 # define Z_OBJ_SERVER(zo)              (php_server_fetch_object(zo))
+# define Z_OBJ_SESSION(zo)             (php_session_fetch_object(zo))
 # define Z_OBJ_BULKWRITE(zo)           (php_bulkwrite_fetch_object(zo))
 # define Z_OBJ_WRITECONCERN(zo)        (php_writeconcern_fetch_object(zo))
 # define Z_OBJ_WRITECONCERNERROR(zo)   (php_writeconcernerror_fetch_object(zo))
@@ -178,6 +183,7 @@ static inline php_phongo_commandsucceededevent_t* php_commandsucceededevent_fetc
 # define Z_READCONCERN_OBJ_P(zv)       ((php_phongo_readconcern_t *)zend_object_store_get_object(zv TSRMLS_CC))
 # define Z_READPREFERENCE_OBJ_P(zv)    ((php_phongo_readpreference_t *)zend_object_store_get_object(zv TSRMLS_CC))
 # define Z_SERVER_OBJ_P(zv)            ((php_phongo_server_t *)zend_object_store_get_object(zv TSRMLS_CC))
+# define Z_SESSION_OBJ_P(zv)           ((php_phongo_session_t *)zend_object_store_get_object(zv TSRMLS_CC))
 # define Z_BULKWRITE_OBJ_P(zv)         ((php_phongo_bulkwrite_t *)zend_object_store_get_object(zv TSRMLS_CC))
 # define Z_WRITECONCERN_OBJ_P(zv)      ((php_phongo_writeconcern_t *)zend_object_store_get_object(zv TSRMLS_CC))
 # define Z_WRITECONCERNERROR_OBJ_P(zv) ((php_phongo_writeconcernerror_t *)zend_object_store_get_object(zv TSRMLS_CC))
@@ -207,6 +213,7 @@ static inline php_phongo_commandsucceededevent_t* php_commandsucceededevent_fetc
 # define Z_OBJ_READCONCERN(zo)         ((php_phongo_readconcern_t *)zo)
 # define Z_OBJ_READPREFERENCE(zo)      ((php_phongo_readpreference_t *)zo)
 # define Z_OBJ_SERVER(zo)              ((php_phongo_server_t *)zo)
+# define Z_OBJ_SESSION(zo)             ((php_phongo_session_t *)zo)
 # define Z_OBJ_BULKWRITE(zo)           ((php_phongo_bulkwrite_t *)zo)
 # define Z_OBJ_WRITECONCERN(zo)        ((php_phongo_writeconcern_t *)zo)
 # define Z_OBJ_WRITECONCERNERROR(zo)   ((php_phongo_writeconcernerror_t *)zo)
@@ -244,6 +251,7 @@ extern zend_class_entry *php_phongo_query_ce;
 extern zend_class_entry *php_phongo_readconcern_ce;
 extern zend_class_entry *php_phongo_readpreference_ce;
 extern zend_class_entry *php_phongo_server_ce;
+extern zend_class_entry *php_phongo_session_ce;
 extern zend_class_entry *php_phongo_bulkwrite_ce;
 extern zend_class_entry *php_phongo_writeconcern_ce;
 extern zend_class_entry *php_phongo_writeconcernerror_ce;
@@ -332,6 +340,7 @@ extern void php_phongo_query_init_ce(INIT_FUNC_ARGS);
 extern void php_phongo_readconcern_init_ce(INIT_FUNC_ARGS);
 extern void php_phongo_readpreference_init_ce(INIT_FUNC_ARGS);
 extern void php_phongo_server_init_ce(INIT_FUNC_ARGS);
+extern void php_phongo_session_init_ce(INIT_FUNC_ARGS);
 extern void php_phongo_writeconcern_init_ce(INIT_FUNC_ARGS);
 extern void php_phongo_writeconcernerror_init_ce(INIT_FUNC_ARGS);
 extern void php_phongo_writeerror_init_ce(INIT_FUNC_ARGS);

php_phongo_structs.h

@@ -106,6 +106,12 @@ typedef struct {
 	PHONGO_ZEND_OBJECT_POST
 } php_phongo_server_t;
 
+typedef struct {
+	PHONGO_ZEND_OBJECT_PRE
+	mongoc_client_session_t *client_session;
+	PHONGO_ZEND_OBJECT_POST
+} php_phongo_session_t;
+
 typedef struct {
 	PHONGO_ZEND_OBJECT_PRE
 	mongoc_write_concern_t *write_concern;

src/MongoDB/Manager.c

@@ -538,6 +538,42 @@ static PHP_METHOD(Manager, selectServer)
 	}
 } /* }}} */
 
+/* {{{ proto MongoDB\Driver\Session MongoDB\Driver\Manager::startSession([array $options = null])
+   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;
+	SUPPRESS_UNUSED_WARNING(return_value_ptr) SUPPRESS_UNUSED_WARNING(return_value_used)
+
+
+	intern = Z_MANAGER_OBJ_P(getThis());
+
+	if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "|a!", &options) == FAILURE) {
+		return;
+	}
+
+	if (options && php_array_exists(options, "causalConsistency")) {
+		cs_opts = mongoc_session_opts_new();
+		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 (cs_opts) {
+		mongoc_session_opts_destroy(cs_opts);
+	}
+
+	if (cs) {
+		phongo_session_init(return_value, cs TSRMLS_CC);
+	} else {
+		phongo_throw_exception_from_bson_error_t(&error TSRMLS_CC);
+	}
+} /* }}} */
+
 /* {{{ MongoDB\Driver\Manager function entries */
 ZEND_BEGIN_ARG_INFO_EX(ai_Manager___construct, 0, 0, 0)
 	ZEND_ARG_INFO(0, uri)
@@ -573,6 +609,10 @@ ZEND_BEGIN_ARG_INFO_EX(ai_Manager_selectServer, 0, 0, 1)
 	ZEND_ARG_OBJ_INFO(0, readPreference, MongoDB\\Driver\\ReadPreference, 1)
 ZEND_END_ARG_INFO()
 
+ZEND_BEGIN_ARG_INFO_EX(ai_Manager_startSession, 0, 0, 0)
+	ZEND_ARG_ARRAY_INFO(0, options, 1)
+ZEND_END_ARG_INFO()
+
 ZEND_BEGIN_ARG_INFO_EX(ai_Manager_void, 0, 0, 0)
 ZEND_END_ARG_INFO()
 
@@ -589,6 +629,7 @@ static zend_function_entry php_phongo_manager_me[] = {
 	PHP_ME(Manager, getServers, ai_Manager_void, ZEND_ACC_PUBLIC|ZEND_ACC_FINAL)
 	PHP_ME(Manager, getWriteConcern, ai_Manager_void, ZEND_ACC_PUBLIC|ZEND_ACC_FINAL)
 	PHP_ME(Manager, selectServer, ai_Manager_selectServer, ZEND_ACC_PUBLIC|ZEND_ACC_FINAL)
+	PHP_ME(Manager, startSession, ai_Manager_startSession, ZEND_ACC_PUBLIC|ZEND_ACC_FINAL)
 	ZEND_NAMED_ME(__wakeup, PHP_FN(MongoDB_disabled___wakeup), ai_Manager_void, ZEND_ACC_PUBLIC|ZEND_ACC_FINAL)
 	PHP_FE_END
 };