mongoc_client_get_handshake_description establishes connection

Author: kevinAlbs

src/libmongoc/doc/mongoc_client_get_handshake_description.rst

@@ -21,21 +21,14 @@ Description
 
 :symbol:`mongoc_client_get_handshake_description` is distinct from :symbol:`mongoc_client_get_server_description`. :symbol:`mongoc_client_get_server_description` returns a server description constructed from monitoring, which may differ from the server description constructed from the connection handshake.
 
-Use this function only for building a language driver that wraps the C Driver. When writing applications in C, higher-level functions automatically select a suitable server.
+:symbol:`mongoc_client_get_handshake_description` will attempt to establish a connection to the server if a connection was not already established. It will perform the MongoDB handshake and authentication if required.
 
-:symbol:`mongoc_client_get_handshake_description` does not attempt to establish a connection to the server if a connection was not already established. If a connection has not been established, this returns ``NULL`` and sets ``error``.
+Use this function only for building a language driver that wraps the C Driver. When writing applications in C, higher-level functions automatically select a suitable server.
 
 Single-threaded client behavior
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-To ensure a connection has been established ensure that the server is selectable (e.g. by calling :symbol:`mongoc_client_select_server`) or that an operation has successfully run on the server (e.g. by sending "ping").
-
-If the established connection has not completed authentication, calling :symbol:`mongoc_client_get_handshake_description` will complete authentication on the connection.
-
-Single-threaded clients only have one active connection to each server. The one connection is used for both monitoring and application operations. However, the server description returned by :symbol:`mongoc_client_get_handshake_description` may still differ from :symbol:`mongoc_client_get_server_description`. Notably, if connected to a load balanced cluster, the :symbol:`mongoc_client_get_server_description` will describe the load balancer server (:symbol:`mongoc_server_description_type` will return "LoadBalancer"). And :symbol:`mongoc_client_get_handshake_description` will describe the backing server.
 
-Pooled client behavior
-^^^^^^^^^^^^^^^^^^^^^^
-To ensure a connection has been established ensure an operation has successfully run on a server (e.g. by sending "ping").
+Single-threaded clients only have one active connection to each server. The one connection is used for both monitoring and application operations. However, the server description returned by :symbol:`mongoc_client_get_handshake_description` may still differ from the server description returned by :symbol:`mongoc_client_get_server_description`. Notably, if connected to a load balanced cluster, the :symbol:`mongoc_client_get_server_description` will describe the load balancer server (:symbol:`mongoc_server_description_type` will return "LoadBalancer"). And :symbol:`mongoc_client_get_handshake_description` will describe the backing server.
 
 Parameters
 ----------
@@ -48,7 +41,7 @@ Parameters
 Returns
 -------
 
-A :symbol:`mongoc_server_description_t` that must be freed with :symbol:`mongoc_server_description_destroy`. If a connection has not been successfully established to a server, returns NULL and ``error`` is filled out.
+A :symbol:`mongoc_server_description_t` that must be freed with :symbol:`mongoc_server_description_destroy`. If a connection has not been successfully established to a server, returns ``NULL`` and ``error`` is filled out.
 
 
 See Also

src/libmongoc/src/mongoc/mongoc-client.c

@@ -3154,7 +3154,7 @@ mongoc_client_get_handshake_description (mongoc_client_t *client,
 
    server_stream = mongoc_cluster_stream_for_server (&client->cluster,
                                                      server_id,
-                                                     false /* reconnect */,
+                                                     true /* reconnect */,
                                                      NULL /* client session */,
                                                      NULL /* reply */,
                                                      error);

src/libmongoc/tests/test-mongoc-client.c

@@ -4080,8 +4080,8 @@ test_mongoc_client_get_handshake_hello_response_pooled (void)
    handshake_sd = mongoc_client_get_handshake_description (
       client, monitor_sd->id, NULL /* opts */, &error);
    ASSERT_OR_PRINT (handshake_sd, error);
-   BSON_ASSERT (MONGOC_SERVER_UNKNOWN !=
-                mongoc_server_description_type (handshake_sd));
+   BSON_ASSERT (
+      0 != strcmp ("Unknown", mongoc_server_description_type (handshake_sd)));
 
    mongoc_server_description_destroy (handshake_sd);
    mongoc_server_description_destroy (invalidated_sd);
@@ -4090,6 +4090,53 @@ test_mongoc_client_get_handshake_hello_response_pooled (void)
    mongoc_client_pool_destroy (pool);
 }
 
+/* Test that calling mongoc_client_get_handshake_description establishes a
+ * connection if a connection has not already been established. */
+void
+test_mongoc_client_get_handshake_establishes_connection_single (void)
+{
+   mongoc_client_t *client;
+   mongoc_server_description_t *handshake_sd;
+   bson_error_t error = {0};
+   uint32_t server_id = 1;
+
+   client = test_framework_new_default_client ();
+
+   handshake_sd = mongoc_client_get_handshake_description (
+      client, server_id, NULL /* opts */, &error);
+   ASSERT_OR_PRINT (handshake_sd, error);
+   BSON_ASSERT (
+      0 != strcmp ("Unknown", mongoc_server_description_type (handshake_sd)));
+
+   mongoc_server_description_destroy (handshake_sd);
+   mongoc_client_destroy (client);
+}
+
+void
+test_mongoc_client_get_handshake_establishes_connection_pooled (void)
+{
+   mongoc_client_pool_t *pool;
+   mongoc_client_t *client;
+   mongoc_server_description_t *handshake_sd;
+   bson_error_t error = {0};
+   uint32_t server_id = 1;
+
+   pool = test_framework_new_default_client_pool ();
+   client = mongoc_client_pool_pop (pool);
+
+   /* The previously established connection should have a valid server
+    * description. */
+   handshake_sd = mongoc_client_get_handshake_description (
+      client, server_id, NULL /* opts */, &error);
+   ASSERT_OR_PRINT (handshake_sd, error);
+   BSON_ASSERT (
+      0 != strcmp ("Unknown", mongoc_server_description_type (handshake_sd)));
+
+   mongoc_server_description_destroy (handshake_sd);
+   mongoc_client_pool_push (pool, client);
+   mongoc_client_pool_destroy (pool);
+}
+
 void
 test_client_install (TestSuite *suite)
 {
@@ -4389,4 +4436,10 @@ test_client_install (TestSuite *suite)
    TestSuite_AddLive (suite,
                       "/Client/get_handshake_hello_response/pooled",
                       test_mongoc_client_get_handshake_hello_response_pooled);
+   TestSuite_AddLive (suite,
+                      "/Client/get_handshake_establishes_connection/single",
+                      test_mongoc_client_get_handshake_establishes_connection_single);
+   TestSuite_AddLive (suite,
+                      "/Client/get_handshake_establishes_connection/pooled",
+                      test_mongoc_client_get_handshake_establishes_connection_pooled);
 }