CDRIVER-3947 Use "hello" command when an API version is declared (#784)

* Use hello command for handshake with versioned API

* Support handling hello command responses

* Deprecate legacy hello terminology

* Test handling hello command responses

* Refactor internal methods to use hello terminology

* Change mock server to also handle hello

* Replace deprecated terminology in test expectations

* Use hello in tests

* Fix speculative auth responder

* Fix legacy hello command usage

* Add test for behaviour when server does not support hello command

* Use legacy hello in tests to avoid failures on old server versions

* Update SDAM spec tests

* Fix memory leak

* Fix wrong command expectations for handshake

* Refactor handshake autoresponders

* Fix wrong comment style

* Rename mongoc_server_description_hello_response

* Use method to retrieve hello response

* Improve deprecation declaration

* Rename methods for hello callbacks

* Fix various test issues

* Rename hello_response method

Author: alcaeus

src/libmongoc/doc/mongoc_server_description_hello_response.rst

@@ -0,0 +1,34 @@
+:man_page: mongoc_server_description_hello_response
+
+mongoc_server_description_hello_response()
+===============================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  const bson_t *
+  mongoc_server_description_hello_response (
+     const mongoc_server_description_t *description);
+
+Parameters
+----------
+
+* ``description``: A :symbol:`mongoc_server_description_t`.
+
+Description
+-----------
+
+The client or client pool periodically runs a
+`"hello" <https://docs.mongodb.org/manual/reference/command/isMaster/>`_
+command on each server, to update its view of the MongoDB deployment. Use
+:symbol:`mongoc_client_get_server_descriptions()` and
+``mongoc_server_description_hello_response()`` to get the most recent "hello"
+response.
+
+Returns
+-------
+
+A reference to a BSON document, owned by the server description. The document is empty if the driver is not connected to the server.
+

src/libmongoc/doc/mongoc_server_description_ismaster.rst

@@ -12,6 +12,15 @@ Synopsis
   mongoc_server_description_ismaster (
      const mongoc_server_description_t *description);
 
+Deprecated
+----------
+
+.. warning::
+
+  This function is deprecated and should not be used in new code.
+
+Please use :doc:`mongoc_server_description_hello_response() <mongoc_server_description_hello_response>` instead.
+
 Parameters
 ----------
 

src/libmongoc/doc/mongoc_server_description_t.rst

@@ -33,6 +33,7 @@ Applications receive a temporary reference to a ``mongoc_server_description_t``
     :maxdepth: 1
 
     mongoc_server_description_destroy
+    mongoc_server_description_hello_response
     mongoc_server_description_host
     mongoc_server_description_id
     mongoc_server_description_ismaster

src/libmongoc/src/mongoc/mongoc-cluster.c

@@ -285,10 +285,11 @@ mongoc_cluster_run_command_opquery (mongoc_cluster_t *cluster,
    _mongoc_rpc_gather (&rpc, &cluster->iov);
    _mongoc_rpc_swab_to_le (&rpc);
 
-   if (compressor_id != -1 && IS_NOT_COMMAND ("ismaster") &&
-       IS_NOT_COMMAND ("saslstart") && IS_NOT_COMMAND ("saslcontinue") &&
-       IS_NOT_COMMAND ("getnonce") && IS_NOT_COMMAND ("authenticate") &&
-       IS_NOT_COMMAND ("createuser") && IS_NOT_COMMAND ("updateuser")) {
+   if (compressor_id != -1 && IS_NOT_COMMAND (HANDSHAKE_CMD_LEGACY_HELLO) &&
+       IS_NOT_COMMAND ("hello") && IS_NOT_COMMAND ("saslstart") &&
+       IS_NOT_COMMAND ("saslcontinue") && IS_NOT_COMMAND ("getnonce") &&
+       IS_NOT_COMMAND ("authenticate") && IS_NOT_COMMAND ("createuser") &&
+       IS_NOT_COMMAND ("updateuser")) {
       output = _mongoc_rpc_compress (cluster, compressor_id, &rpc, error);
       if (output == NULL) {
          GOTO (done);
@@ -730,11 +731,11 @@ mongoc_cluster_run_command_parts (mongoc_cluster_t *cluster,
 /*
  *--------------------------------------------------------------------------
  *
- * _mongoc_stream_run_ismaster --
+ * _mongoc_stream_run_hello --
  *
- *       Run an ismaster command on the given stream. If
+ *       Run a hello command on the given stream. If
  *       @negotiate_sasl_supported_mechs is true, then saslSupportedMechs is
- *       added to the ismaster command.
+ *       added to the hello command.
  *
  * Returns:
  *       A mongoc_server_description_t you must destroy or NULL. If the call
@@ -743,18 +744,18 @@ mongoc_cluster_run_command_parts (mongoc_cluster_t *cluster,
  *--------------------------------------------------------------------------
  */
 static mongoc_server_description_t *
-_mongoc_stream_run_ismaster (mongoc_cluster_t *cluster,
-                             mongoc_stream_t *stream,
-                             const char *address,
-                             uint32_t server_id,
-                             bool negotiate_sasl_supported_mechs,
-                             mongoc_scram_cache_t *scram_cache,
-                             mongoc_scram_t *scram,
-                             bson_t *speculative_auth_response /* OUT */,
-                             bson_error_t *error)
+_mongoc_stream_run_hello (mongoc_cluster_t *cluster,
+                          mongoc_stream_t *stream,
+                          const char *address,
+                          uint32_t server_id,
+                          bool negotiate_sasl_supported_mechs,
+                          mongoc_scram_cache_t *scram_cache,
+                          mongoc_scram_t *scram,
+                          bson_t *speculative_auth_response /* OUT */,
+                          bson_error_t *error)
 {
    const bson_t *command;
-   mongoc_cmd_t ismaster_cmd;
+   mongoc_cmd_t hello_cmd;
    bson_t reply;
    int64_t start;
    int64_t rtt_msec;
@@ -813,15 +814,15 @@ _mongoc_stream_run_ismaster (mongoc_cluster_t *cluster,
     * last known ismaster indicates the server supports a newer wire protocol.
     */
    server_stream->sd->max_wire_version = WIRE_VERSION_MIN;
-   memset (&ismaster_cmd, 0, sizeof (ismaster_cmd));
-   ismaster_cmd.db_name = "admin";
-   ismaster_cmd.command = command;
-   ismaster_cmd.command_name = _mongoc_get_command_name (command);
-   ismaster_cmd.query_flags = MONGOC_QUERY_SLAVE_OK;
-   ismaster_cmd.server_stream = server_stream;
+   memset (&hello_cmd, 0, sizeof (hello_cmd));
+   hello_cmd.db_name = "admin";
+   hello_cmd.command = command;
+   hello_cmd.command_name = _mongoc_get_command_name (command);
+   hello_cmd.query_flags = MONGOC_QUERY_SLAVE_OK;
+   hello_cmd.server_stream = server_stream;
 
    if (!mongoc_cluster_run_command_private (
-          cluster, &ismaster_cmd, &reply, error)) {
+          cluster, &hello_cmd, &reply, error)) {
       if (negotiate_sasl_supported_mechs) {
          if (bson_iter_init_find (&iter, &reply, "ok") &&
              !bson_iter_as_bool (&iter)) {
@@ -845,8 +846,8 @@ _mongoc_stream_run_ismaster (mongoc_cluster_t *cluster,
       sizeof (mongoc_server_description_t));
 
    mongoc_server_description_init (sd, address, server_id);
-   /* send the error from run_command IN to handle_ismaster */
-   mongoc_server_description_handle_ismaster (sd, &reply, rtt_msec, error);
+   /* send the error from run_command IN to handle_hello */
+   mongoc_server_description_handle_hello (sd, &reply, rtt_msec, error);
 
    if (cluster->requires_auth && speculative_auth_response) {
       _mongoc_topology_scanner_parse_speculative_authentication (
@@ -877,28 +878,28 @@ _mongoc_stream_run_ismaster (mongoc_cluster_t *cluster,
 /*
  *--------------------------------------------------------------------------
  *
- * _mongoc_cluster_run_ismaster --
+ * _mongoc_cluster_run_hello --
  *
- *       Run an initial ismaster command for the given node and handle result.
+ *       Run an initial hello command for the given node and handle result.
  *
  * Returns:
  *       mongoc_server_description_t on success, NULL otherwise.
  *       the mongoc_server_description_t MUST BE DESTROYED BY THE CALLER.
  *
  * Side effects:
  *       Makes a blocking I/O call, updates cluster->topology->description
- *       with ismaster result.
+ *       with hello result.
  *
  *--------------------------------------------------------------------------
  */
 static mongoc_server_description_t *
-_mongoc_cluster_run_ismaster (mongoc_cluster_t *cluster,
-                              mongoc_cluster_node_t *node,
-                              uint32_t server_id,
-                              mongoc_scram_cache_t *scram_cache,
-                              mongoc_scram_t *scram /* OUT */,
-                              bson_t *speculative_auth_response /* OUT */,
-                              bson_error_t *error /* OUT */)
+_mongoc_cluster_run_hello (mongoc_cluster_t *cluster,
+                           mongoc_cluster_node_t *node,
+                           uint32_t server_id,
+                           mongoc_scram_cache_t *scram_cache,
+                           mongoc_scram_t *scram /* OUT */,
+                           bson_t *speculative_auth_response /* OUT */,
+                           bson_error_t *error /* OUT */)
 {
    mongoc_server_description_t *sd;
 
@@ -908,7 +909,7 @@ _mongoc_cluster_run_ismaster (mongoc_cluster_t *cluster,
    BSON_ASSERT (node);
    BSON_ASSERT (node->stream);
 
-   sd = _mongoc_stream_run_ismaster (
+   sd = _mongoc_stream_run_hello (
       cluster,
       node->stream,
       node->connection_address,
@@ -2095,18 +2096,18 @@ _mongoc_cluster_add_node (mongoc_cluster_t *cluster,
    cluster_node =
       _mongoc_cluster_node_new (stream, generation, host->host_and_port);
 
-   sd = _mongoc_cluster_run_ismaster (cluster,
-                                      cluster_node,
-                                      server_id,
-                                      cluster->scram_cache,
-                                      &scram,
-                                      &speculative_auth_response,
-                                      error);
+   sd = _mongoc_cluster_run_hello (cluster,
+                                   cluster_node,
+                                   server_id,
+                                   cluster->scram_cache,
+                                   &scram,
+                                   &speculative_auth_response,
+                                   error);
    if (!sd) {
       GOTO (error);
    }
 
-   _mongoc_handshake_parse_sasl_supported_mechs (&sd->last_is_master,
+   _mongoc_handshake_parse_sasl_supported_mechs (&sd->last_hello_response,
                                                  &sasl_supported_mechs);
 
    if (cluster->requires_auth) {

src/libmongoc/src/mongoc/mongoc-cmd.c

@@ -1073,7 +1073,8 @@ mongoc_cmd_is_compressible (mongoc_cmd_t *cmd)
    BSON_ASSERT (cmd);
    BSON_ASSERT (cmd->command_name);
 
-   return !!strcasecmp (cmd->command_name, "ismaster") &&
+   return !!strcasecmp (cmd->command_name, "hello") &&
+          !!strcasecmp (cmd->command_name, HANDSHAKE_CMD_LEGACY_HELLO) &&
           !!strcasecmp (cmd->command_name, "authenticate") &&
           !!strcasecmp (cmd->command_name, "getnonce") &&
           !!strcasecmp (cmd->command_name, "saslstart") &&

src/libmongoc/src/mongoc/mongoc-handshake-private.h

@@ -35,6 +35,9 @@ BSON_BEGIN_DECLS
 #define HANDSHAKE_OS_ARCHITECTURE_MAX 32
 #define HANDSHAKE_DRIVER_NAME_MAX 64
 #define HANDSHAKE_DRIVER_VERSION_MAX 32
+
+#define HANDSHAKE_CMD_LEGACY_HELLO "isMaster"
+#define HANDSHAKE_RESPONSE_LEGACY_HELLO "ismaster"
 /* platform has no fixed max size. It can just occupy the remaining
  * available space in the document. */
 

src/libmongoc/src/mongoc/mongoc-handshake.h

@@ -61,7 +61,7 @@ BSON_BEGIN_DECLS
  * Returns true if the given fields are set successfully. Otherwise, it returns
  * false and logs an error.
  *
- * The default handshake data the driver sends with "isMaster" looks something
+ * The default handshake data the driver sends with "hello" looks something
  * like:
  *  client: {
  *    driver: {

src/libmongoc/src/mongoc/mongoc-server-description-private.h

@@ -62,8 +62,8 @@ struct _mongoc_server_description_t {
    mongoc_host_list_t host;
    int64_t round_trip_time_msec;
    int64_t last_update_time_usec;
-   bson_t last_is_master;
-   bool has_is_master;
+   bson_t last_hello_response;
+   bool has_hello_response;
    const char *connection_address;
    /* SDAM dictates storing me/hosts/passives/arbiters after being "normalized
     * to lower-case" Instead, they are stored in the casing they are received,
@@ -149,10 +149,10 @@ mongoc_server_description_update_rtt (mongoc_server_description_t *server,
                                       int64_t rtt_msec);
 
 void
-mongoc_server_description_handle_ismaster (mongoc_server_description_t *sd,
-                                           const bson_t *reply,
-                                           int64_t rtt_msec,
-                                           const bson_error_t *error /* IN */);
+mongoc_server_description_handle_hello (mongoc_server_description_t *sd,
+                                        const bson_t *hello_response,
+                                        int64_t rtt_msec,
+                                        const bson_error_t *error /* IN */);
 
 void
 mongoc_server_description_filter_stale (mongoc_server_description_t **sds,