CDRIVER-5577 add serverMonitoringMode URI option (#1724)

* add sdam-options spec test

* add duplication test

* implement serverMonitoringMode parsing and logic

* add tests to mimic serverMonitoringMode.yml

* implement stream/poll monitoring logic based on serverMonitoringMode

* add FAAS env tests and change test to only run on live servers

* create pool with test_framework fx

* add enum in server-monitor.c

* add documentation for new public API

* validation improvements in mongoc-uri

* address test comments

Author: joshbsiegel

src/libmongoc/doc/mongoc_uri_get_server_monitoring_mode.rst

@@ -0,0 +1,28 @@
+:man_page: mongoc_uri_get_server_monitoring_mode
+
+mongoc_uri_get_server_monitoring_mode()
+=======================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  const char *
+  mongoc_uri_get_server_monitoring_mode (const mongoc_uri_t *uri);
+
+Parameters
+----------
+
+* ``uri``: A :symbol:`mongoc_uri_t`.
+
+Description
+-----------
+
+Fetches the ``serverMonitoringMode`` parameter to an URI if provided.
+
+Returns
+-------
+
+A string which should not be modified or freed. Returns "auto" if the ``serverMonitoringMode`` parameter was not provided to ``uri``.
+

src/libmongoc/doc/mongoc_uri_set_server_monitoring_mode.rst

@@ -0,0 +1,31 @@
+:man_page: mongoc_uri_set_server_monitoring_mode
+
+mongoc_uri_set_server_monitoring_mode()
+=======================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  bool
+  mongoc_uri_set_server_monitoring_mode (mongoc_uri_t *uri, const char *value);
+
+Parameters
+----------
+
+* ``uri``: A :symbol:`mongoc_uri_t`.
+* ``value``: The new ``serverMonitoringMode`` value.
+
+Description
+-----------
+
+Sets the ``serverMonitoringMode`` URI option to ``value`` after the URI has been parsed from a string.
+
+Updates the option in-place if already set, otherwise appends it to the URI's :symbol:`bson:bson_t` of options.
+
+Returns
+-------
+
+Returns false if the ``value`` is not "auto", "poll", or "stream".
+

src/libmongoc/doc/mongoc_uri_t.rst

@@ -308,6 +308,7 @@ MONGOC_URI_SAFE                            safe                              {tr
     mongoc_uri_get_read_prefs
     mongoc_uri_get_read_prefs_t
     mongoc_uri_get_replica_set
+    mongoc_uri_get_server_monitoring_mode
     mongoc_uri_get_service
     mongoc_uri_get_ssl
     mongoc_uri_get_string
@@ -336,6 +337,7 @@ MONGOC_URI_SAFE                            safe                              {tr
     mongoc_uri_set_password
     mongoc_uri_set_read_concern
     mongoc_uri_set_read_prefs_t
+    mongoc_uri_set_server_monitoring_mode
     mongoc_uri_set_username
     mongoc_uri_set_write_concern
     mongoc_uri_unescape

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

@@ -24,6 +24,11 @@
 #include "mongoc-topology-private.h"
 
 /* For background monitoring of a single server. */
+typedef enum {
+   MONGOC_SERVER_MONITORING_AUTO = 0,
+   MONGOC_SERVER_MONITORING_POLL,
+   MONGOC_SERVER_MONITORING_STREAM
+} mongoc_server_monitoring_mode_t;
 
 typedef struct _mongoc_server_monitor_t mongoc_server_monitor_t;
 

src/libmongoc/src/mongoc/mongoc-server-monitor.c

@@ -88,6 +88,7 @@ struct _mongoc_server_monitor_t {
    mongoc_server_description_t *description;
    uint32_t server_id;
    bool is_rtt;
+   mongoc_server_monitoring_mode_t mode;
 };
 
 static BSON_GNUC_PRINTF (3, 4) void _server_monitor_log (mongoc_server_monitor_t *server_monitor,
@@ -789,6 +790,24 @@ _update_topology_description (mongoc_server_monitor_t *server_monitor, mongoc_se
    mc_tpld_modify_commit (tdmod);
 }
 
+/* Get the mode enum based on the uri
+ *
+ * Called during server monitor creation
+ */
+static mongoc_server_monitoring_mode_t
+_server_monitor_get_mode_enum (mongoc_server_monitor_t *server_monitor)
+{
+   const char *mode_str = mongoc_uri_get_server_monitoring_mode (server_monitor->uri);
+
+   if (strcmp (mode_str, "poll") == 0) {
+      return MONGOC_SERVER_MONITORING_POLL;
+   } else if (strcmp (mode_str, "stream") == 0) {
+      return MONGOC_SERVER_MONITORING_STREAM;
+   } else {
+      return MONGOC_SERVER_MONITORING_AUTO;
+   }
+}
+
 /* Create a new server monitor.
  *
  * Called during reconcile.
@@ -820,6 +839,7 @@ mongoc_server_monitor_new (mongoc_topology_t *topology,
    server_monitor->apm_context = td->apm_context;
    server_monitor->initiator = topology->scanner->initiator;
    server_monitor->initiator_context = topology->scanner->initiator_context;
+   server_monitor->mode = _server_monitor_get_mode_enum (server_monitor);
    mongoc_cond_init (&server_monitor->shared.cond);
    bson_mutex_init (&server_monitor->shared.mutex);
    return server_monitor;
@@ -949,11 +969,15 @@ _server_monitor_check_server (mongoc_server_monitor_t *server_monitor,
       GOTO (exit);
    }
 
-   if (!bson_empty (&previous_description->topology_version) &&
-       _mongoc_handshake_get ()->env == MONGOC_HANDSHAKE_ENV_NONE) {
+   if (server_monitor->mode != MONGOC_SERVER_MONITORING_POLL && !bson_empty (&previous_description->topology_version) &&
+       (_mongoc_handshake_get ()->env == MONGOC_HANDSHAKE_ENV_NONE ||
+        server_monitor->mode == MONGOC_SERVER_MONITORING_STREAM)) {
       // Use stream monitoring if:
+      // - serverMonitoringMode != "poll"
       // - Server supports stream monitoring (indicated by `topologyVersion`).
-      // - Application is not in an FaaS environment (e.g. AWS Lambda).
+      // - ONE OF:
+      //    - Application is not in an FaaS environment (e.g. AWS Lambda).
+      //    - serverMonitoringMode == "stream"
       awaited = true;
       _server_monitor_heartbeat_started (server_monitor, awaited);
       MONITOR_LOG (server_monitor, "awaitable hello");

src/libmongoc/src/mongoc/mongoc-uri.c

@@ -749,8 +749,8 @@ bool
 mongoc_uri_option_is_utf8 (const char *key)
 {
    return !strcasecmp (key, MONGOC_URI_APPNAME) || !strcasecmp (key, MONGOC_URI_REPLICASET) ||
-          !strcasecmp (key, MONGOC_URI_READPREFERENCE) || !strcasecmp (key, MONGOC_URI_SRVSERVICENAME) ||
-          !strcasecmp (key, MONGOC_URI_TLSCERTIFICATEKEYFILE) ||
+          !strcasecmp (key, MONGOC_URI_READPREFERENCE) || !strcasecmp (key, MONGOC_URI_SERVERMONITORINGMODE) ||
+          !strcasecmp (key, MONGOC_URI_SRVSERVICENAME) || !strcasecmp (key, MONGOC_URI_TLSCERTIFICATEKEYFILE) ||
           !strcasecmp (key, MONGOC_URI_TLSCERTIFICATEKEYFILEPASSWORD) || !strcasecmp (key, MONGOC_URI_TLSCAFILE) ||
           /* deprecated options */
           !strcasecmp (key, MONGOC_URI_SSLCLIENTCERTIFICATEKEYFILE) ||
@@ -1142,6 +1142,11 @@ mongoc_uri_apply_options (mongoc_uri_t *uri, const bson_t *options, bool from_dn
             goto UNSUPPORTED_VALUE;
          }
 
+      } else if (!strcmp (key, MONGOC_URI_SERVERMONITORINGMODE)) {
+         if (!mongoc_uri_set_server_monitoring_mode (uri, value)) {
+            goto UNSUPPORTED_VALUE;
+         }
+
       } else if (mongoc_uri_option_is_utf8 (key)) {
          mongoc_uri_bson_append_or_replace_key (&uri->options, canon, value);
 
@@ -2350,6 +2355,30 @@ mongoc_uri_get_ssl (const mongoc_uri_t *uri) /* IN */
    return mongoc_uri_get_tls (uri);
 }
 
+const char *
+mongoc_uri_get_server_monitoring_mode (const mongoc_uri_t *uri)
+{
+   BSON_ASSERT_PARAM (uri);
+
+   return mongoc_uri_get_option_as_utf8 (uri, MONGOC_URI_SERVERMONITORINGMODE, "auto");
+}
+
+
+bool
+mongoc_uri_set_server_monitoring_mode (mongoc_uri_t *uri, const char *value)
+{
+   BSON_ASSERT_PARAM (uri);
+   BSON_ASSERT_PARAM (value);
+
+   // Check for valid value
+   if (strcmp (value, "stream") && strcmp (value, "poll") && strcmp (value, "auto")) {
+      return false;
+   }
+
+   mongoc_uri_bson_append_or_replace_key (&uri->options, MONGOC_URI_SERVERMONITORINGMODE, value);
+   return true;
+}
+
 /*
  *--------------------------------------------------------------------------
  *
@@ -2886,6 +2915,8 @@ mongoc_uri_set_option_as_utf8 (mongoc_uri_t *uri, const char *option_orig, const
    }
    if (!bson_strcasecmp (option, MONGOC_URI_APPNAME)) {
       return mongoc_uri_set_appname (uri, value);
+   } else if (!bson_strcasecmp (option, MONGOC_URI_SERVERMONITORINGMODE)) {
+      return mongoc_uri_set_server_monitoring_mode (uri, value);
    } else {
       option_lowercase = lowercase_str_new (option);
       mongoc_uri_bson_append_or_replace_key (&uri->options, option_lowercase, value);

src/libmongoc/src/mongoc/mongoc-uri.h

@@ -57,6 +57,7 @@
 #define MONGOC_URI_RETRYREADS "retryreads"
 #define MONGOC_URI_RETRYWRITES "retrywrites"
 #define MONGOC_URI_SAFE "safe"
+#define MONGOC_URI_SERVERMONITORINGMODE "servermonitoringmode"
 #define MONGOC_URI_SERVERSELECTIONTIMEOUTMS "serverselectiontimeoutms"
 #define MONGOC_URI_SERVERSELECTIONTRYONCE "serverselectiontryonce"
 #define MONGOC_URI_SLAVEOK "slaveok"
@@ -197,6 +198,10 @@ MONGOC_EXPORT (const mongoc_read_concern_t *)
 mongoc_uri_get_read_concern (const mongoc_uri_t *uri);
 MONGOC_EXPORT (void)
 mongoc_uri_set_read_concern (mongoc_uri_t *uri, const mongoc_read_concern_t *rc);
+MONGOC_EXPORT (const char *)
+mongoc_uri_get_server_monitoring_mode (const mongoc_uri_t *uri);
+MONGOC_EXPORT (bool)
+mongoc_uri_set_server_monitoring_mode (mongoc_uri_t *uri, const char *value);
 
 BSON_END_DECLS
 

src/libmongoc/tests/json/uri-options/sdam-options.json

@@ -0,0 +1,46 @@
+{
+  "tests": [
+    {
+      "description": "serverMonitoringMode=auto",
+      "uri": "mongodb://example.com/?serverMonitoringMode=auto",
+      "valid": true,
+      "warning": false,
+      "hosts": null,
+      "auth": null,
+      "options": {
+        "serverMonitoringMode": "auto"
+      }
+    },
+    {
+      "description": "serverMonitoringMode=stream",
+      "uri": "mongodb://example.com/?serverMonitoringMode=stream",
+      "valid": true,
+      "warning": false,
+      "hosts": null,
+      "auth": null,
+      "options": {
+        "serverMonitoringMode": "stream"
+      }
+    },
+    {
+      "description": "serverMonitoringMode=poll",
+      "uri": "mongodb://example.com/?serverMonitoringMode=poll",
+      "valid": true,
+      "warning": false,
+      "hosts": null,
+      "auth": null,
+      "options": {
+        "serverMonitoringMode": "poll"
+      }
+    },
+    {
+      "description": "invalid serverMonitoringMode",
+      "uri": "mongodb://example.com/?serverMonitoringMode=invalid",
+      "valid": true,
+      "warning": true,
+      "hosts": null,
+      "auth": null,
+      "options": {}
+    }
+  ]
+}