CDRIVER-3821 implement versioned api

Author: samantharitter

src/libmongoc/CMakeLists.txt

@@ -534,6 +534,7 @@ set (SOURCES ${SOURCES}
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-read-concern.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-read-prefs.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-rpc.c
+   ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-server-api.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-server-description.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-server-stream.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-client-session.c
@@ -598,6 +599,7 @@ set (HEADERS
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-prelude.h
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-read-concern.h
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-read-prefs.h
+   ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-server-api.h
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-server-description.h
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-client-session.h
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-socket.h
@@ -993,6 +995,7 @@ set (test-libmongoc-sources
    ${PROJECT_SOURCE_DIR}/tests/test-mongoc-usleep.c
    ${PROJECT_SOURCE_DIR}/tests/test-mongoc-util.c
    ${PROJECT_SOURCE_DIR}/tests/test-mongoc-version.c
+   ${PROJECT_SOURCE_DIR}/tests/test-mongoc-versioned-api.c
    ${PROJECT_SOURCE_DIR}/tests/test-mongoc-with-transaction.c
    ${PROJECT_SOURCE_DIR}/tests/test-mongoc-write-commands.c
    ${PROJECT_SOURCE_DIR}/tests/test-mongoc-write-concern.c

src/libmongoc/doc/api.rst

@@ -45,6 +45,8 @@ API Reference
    mongoc_read_prefs_t
    mongoc_remove_flags_t
    mongoc_reply_flags_t
+   mongoc_server_api_t
+   mongoc_server_api_version_t
    mongoc_server_description_t
    mongoc_session_opt_t
    mongoc_socket_t

src/libmongoc/doc/mongoc_client_pool_set_server_api.rst

@@ -0,0 +1,28 @@
+:man_page: mongoc_client_pool_set_server_api
+
+mongoc_client_pool_set_server_api()
+===================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  bool
+  mongoc_client_pool_set_server_api (mongoc_client_pool_t *pool,
+                                     const mongoc_server_api_t *api,
+                                     bson_error_t *error);
+
+Set the API version to use for clients created through ``pool``. Once the API version is set on a pool, it may not be changed to a new value. Attempting to do so will cause this method to fail and set ``error``.
+
+Parameters
+----------
+
+* ``pool``: A :symbol:`mongoc_client_pool_t`.
+* ``api``: A :symbol:`mongoc_server_api_t`.
+* ``error``: A :symbol:`bson_error_t`.
+
+Returns
+-------
+
+True if the version was successfully set, false if not. On failure, ``error`` will be set.

src/libmongoc/doc/mongoc_client_pool_t.rst

@@ -40,6 +40,7 @@ Example
     mongoc_client_pool_set_apm_callbacks
     mongoc_client_pool_set_appname
     mongoc_client_pool_set_error_api
+    mongoc_client_pool_set_server_api
     mongoc_client_pool_set_ssl_opts
     mongoc_client_pool_try_pop
 

src/libmongoc/doc/mongoc_client_set_server_api.rst

@@ -0,0 +1,28 @@
+:man_page: mongoc_client_set_server_api
+
+mongoc_client_set_server_api()
+==============================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  bool
+  mongoc_client_set_server_api (mongoc_client_t *client,
+                                const mongoc_server_api_t *api,
+                                bson_error_t *error);
+
+Set the API version to use for ``client``. Once the API version is set on a client, it may not be changed to a new value. Attempting to do so will cause this method to fail and set ``error``.
+
+Parameters
+----------
+
+* ``client``: A :symbol:`mongoc_client_t`.
+* ``api``: A :symbol:`mongoc_server_api_t`.
+* ``error``: A :symbol:`bson_error_t`.
+
+Returns
+-------
+
+True if the version was successfully set, false if not. On failure, ``error`` will be set.

src/libmongoc/doc/mongoc_client_t.rst

@@ -82,6 +82,7 @@ Example
     mongoc_client_set_error_api
     mongoc_client_set_read_concern
     mongoc_client_set_read_prefs
+    mongoc_client_set_server_api
     mongoc_client_set_ssl_opts
     mongoc_client_set_stream_initiator
     mongoc_client_set_write_concern

src/libmongoc/doc/mongoc_server_api_copy.rst

@@ -0,0 +1,24 @@
+:man_page: mongoc_server_api_copy
+
+mongoc_server_api_copy()
+========================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  mongoc_server_api_t *
+  mongoc_server_api_copy (const mongoc_server_api_t *api);
+
+Creates a deep copy of ``api``.
+
+Parameters
+----------
+
+* ``api``: A :symbol:`mongoc_server_api_t`.
+
+Returns
+-------
+
+Returns a newly allocated copy of ``api`` that must be freed with :symbol:`mongoc_server_api_destroy()` when no longer in use.

src/libmongoc/doc/mongoc_server_api_deprecation_errors.rst

@@ -0,0 +1,21 @@
+:man_page: mongoc_server_api_deprecation_errors
+
+mongoc_server_api_deprecation_errors()
+======================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void
+  mongoc_server_api_deprecation_errors (mongoc_server_api_t *api,
+                                        bool deprecation_errors);
+
+Set whether or not to error on commands that are deprecated in this API version.
+
+Parameters
+----------
+
+* ``api``: A :symbol:`mongoc_server_api_t`.
+* ``deprecation_errors``: Whether or not to error on commands that are deprecated.

src/libmongoc/doc/mongoc_server_api_destroy.rst

@@ -0,0 +1,14 @@
+:man_page: mongoc_server_api_destroy
+
+mongoc_server_api_destroy()
+===========================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void
+  mongoc_server_api_destroy (mongoc_server_api_t *api);
+
+Free a :symbol:`mongoc_server_api_t`. Does nothing if ``api`` is NULL.

src/libmongoc/doc/mongoc_server_api_new.rst

@@ -0,0 +1,19 @@
+:man_page: mongoc_server_api_new
+
+mongoc_server_api_new()
+=======================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  mongoc_server_api_t *
+  mongoc_server_api_new (mongoc_server_api_version_t version);
+
+Create a struct to hold server API preferences.
+
+Returns
+-------
+
+A new ``mongoc_server_api_t`` you must free with :symbol:`mongoc_server_api_destroy`.

src/libmongoc/doc/mongoc_server_api_strict.rst

@@ -0,0 +1,20 @@
+:man_page: mongoc_server_api_strict
+
+mongoc_server_api_strict()
+==========================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void
+  mongoc_server_api_strict (mongoc_server_api_t *api, bool strict);
+
+Set whether to be strict about the list of allowed commands in this API version.
+
+Parameters
+----------
+
+* ``api``: A :symbol:`mongoc_server_api_t`.
+* ``strict``: Whether or not to be struct about the list of allowed API commands.

src/libmongoc/doc/mongoc_server_api_t.rst

@@ -0,0 +1,30 @@
+:man_page: mongoc_server_api_t
+
+mongoc_server_api_t
+===================
+
+A versioned API to use for connections.
+
+Synopsis
+--------
+
+Used to specify which version of the MongoDB server's API to use for driver connections.
+
+The server API type takes a :symbol:`mongoc_server_api_version_t`. It can optionally be strict about the list of allowed commands in that API version, and can also optionally provide errors for deprecated commands in that API version.
+
+A :symbol:`mongoc_server_api_t` can be set on a client, and will then be sent to MongoDB for most commands run using that client.
+
+.. only:: html
+
+  Functions
+  ---------
+
+  .. toctree::
+    :titlesonly:
+    :maxdepth: 1
+
+    mongoc_server_api_copy
+    mongoc_server_api_deprecation_errors
+    mongoc_server_api_destroy
+    mongoc_server_api_new
+    mongoc_server_api_strict

src/libmongoc/doc/mongoc_server_api_version_from_string.rst

@@ -0,0 +1,26 @@
+:man_page: mongoc_server_api_version_from_string
+
+mongoc_server_api_version_from_string()
+=======================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  bool
+  mongoc_server_api_version_from_string (const char *version,
+                                         mongoc_server_api_version_t *out);
+
+Given a string ``version``, populates ``out`` with the equivalent :symbol:`mongoc_server_api_version_t` if ``version`` represents a valid API version.
+
+Paremeters
+----------
+
+* ``version``: A string representing the version identifier.
+* ``out``: A pointer to a :symbol:`mongoc_server_api_version_t`.
+
+Returns
+-------
+
+True on success, false on failure. On success, ``out`` is populated with the converted version string. On failure, ``out`` is not altered.

src/libmongoc/doc/mongoc_server_api_version_t.rst

@@ -0,0 +1,34 @@
+:man_page: mongoc_server_api_version_t
+
+mongoc_server_api_version_t
+===========================
+
+A representation of server API version numbers.
+
+Synopsis
+--------
+
+Used to specify which version of the MongoDB server's API to use for driver connections.
+
+Supported API Versions
+----------------------
+
+The driver currently supports the following MongoDB API versions:
+
+====================  ======================
+Enum value            MongoDB version string
+====================  ======================
+MONGOC_SERVER_API_V1  "1"
+====================  ======================
+
+.. only:: html
+
+  Functions
+  ---------
+
+  .. toctree::
+    :titlesonly:
+    :maxdepth: 1
+
+    mongoc_server_api_version_from_string
+    mongoc_server_api_version_to_string

src/libmongoc/doc/mongoc_server_api_version_to_string.rst

@@ -0,0 +1,24 @@
+:man_page: mongoc_server_api_version_to_string
+
+mongoc_server_api_version_to_string()
+=====================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  const char *
+  mongoc_server_api_version_to_string (mongoc_server_api_version_t version);
+
+Returns the string representation of ``version``, or NULL if ``version`` has no string representation.
+
+Parameters
+----------
+
+* ``version``: A :symbol:`mongoc_server_api_version_t`
+
+Returns
+-------
+
+Returns the string representation of ``version`` or NULL.  The returned string should not be freed.

src/libmongoc/src/mongoc/CMakeLists.txt

@@ -45,6 +45,7 @@ set (src_libmongoc_src_mongoc_DIST_hs
    mongoc-rand.h
    mongoc-read-concern.h
    mongoc-read-prefs.h
+   mongoc-server-api.h
    mongoc-server-description.h
    mongoc-client-session.h
    mongoc-socket.h
@@ -140,6 +141,7 @@ set (src_libmongoc_src_mongoc_DIST_noinst_hs
    mongoc-scram-private.h
    mongoc-secure-channel-private.h
    mongoc-secure-transport-private.h
+   mongoc-server-api-private.h
    mongoc-server-description-private.h
    mongoc-server-stream-private.h
    mongoc-server-monitor-private.h
@@ -228,6 +230,7 @@ set (src_libmongoc_src_mongoc_DIST_cs
    mongoc-read-concern.c
    mongoc-read-prefs.c
    mongoc-rpc.c
+   mongoc-server-api.c
    mongoc-server-description.c
    mongoc-server-stream.c
    mongoc-client-session.c