CDRIVER-4689 add mongoc_oidc_callback_t

src/libmongoc/CMakeLists.txt

@@ -597,6 +597,7 @@ set (MONGOC_SOURCES
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-log-and-monitor-private.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-memcmp.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-cmd.c
+   ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-oidc-callback.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-opcode.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-optional.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-opts-helpers.c
@@ -717,6 +718,7 @@ set (HEADERS
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-iovec.h
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-log.h
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-macros.h
+   ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-oidc-callback.h
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-opcode.h
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-optional.h
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-prelude.h
@@ -1057,6 +1059,7 @@ set (test-libmongoc-sources
    ${PROJECT_SOURCE_DIR}/tests/test-mongoc-max-staleness.c
    ${PROJECT_SOURCE_DIR}/tests/test-mongoc-mongohouse.c
    ${PROJECT_SOURCE_DIR}/tests/test-mongoc-mongos-pinning.c
+   ${PROJECT_SOURCE_DIR}/tests/test-mongoc-oidc-callback.c
    ${PROJECT_SOURCE_DIR}/tests/test-mongoc-opts.c
    ${PROJECT_SOURCE_DIR}/tests/test-mongoc-primary-stepdown.c
    ${PROJECT_SOURCE_DIR}/tests/test-mongoc-queue.c

src/libmongoc/doc/api.rst

@@ -39,6 +39,10 @@ API Reference
    mongoc_host_list_t
    mongoc_insert_flags_t
    mongoc_iovec_t
+   mongoc_oidc_callback_fn_t
+   mongoc_oidc_callback_params_t
+   mongoc_oidc_callback_t
+   mongoc_oidc_credential_t
    mongoc_optional_t
    mongoc_query_flags_t
    mongoc_rand

src/libmongoc/doc/mongoc_oidc_callback_destroy.rst

@@ -0,0 +1,27 @@
+:man_page: mongoc_oidc_callback_destroy
+
+mongoc_oidc_callback_destroy()
+==============================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void
+  mongoc_oidc_callback_destroy (mongoc_oidc_callback_t *callback)
+
+Release all resources associated with the given :symbol:`mongoc_oidc_callback_t` object.
+
+.. warning::
+
+    The lifetime of the object pointed to by ``user_data`` is managed the user, not by :symbol:`mongoc_oidc_callback_t`!
+
+Parameters
+----------
+
+* ``callback``: a :symbol:`mongoc_oidc_callback_t` or ``NULL``.
+
+.. seealso::
+
+  - :symbol:`mongoc_oidc_callback_t`

src/libmongoc/doc/mongoc_oidc_callback_fn_t.rst

@@ -0,0 +1,35 @@
+:man_page: mongoc_oidc_callback_fn_t
+
+mongoc_oidc_callback_fn_t
+=========================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  typedef mongoc_oidc_credential_t *(*mongoc_oidc_callback_fn_t) (mongoc_oidc_callback_params_t *params);
+
+The type of the function pointer stored by :symbol:`mongoc_oidc_callback_t`.
+
+Parameters
+----------
+
+* ``params``: A :symbol:`mongoc_oidc_callback_params_t` object representing in/out parameters of a :symbol:`mongoc_oidc_callback_t`.
+
+Returns
+-------
+
+A :symbol:`mongoc_oidc_credential_t` object created with :symbol:`mongoc_oidc_credential_new()`, or ``NULL`` to indicate an error or timeout.
+
+* The function MUST return a :symbol:`mongoc_oidc_credential_t` object to indicate success.
+* The function MUST return ``NULL`` to indicate an error.
+* The function MUST call :symbol:`mongoc_oidc_callback_params_cancel_with_timeout()` before returning ``NULL`` to indicate a timeout instead of an error.
+
+The ``cancel_with_timeout`` out parameter is ignored if the return value is not ``NULL``.
+
+.. seealso::
+
+  - :symbol:`mongoc_oidc_callback_t`
+  - :symbol:`mongoc_oidc_callback_params_t`
+  - :symbol:`mongoc_oidc_credential_t`

src/libmongoc/doc/mongoc_oidc_callback_get_fn.rst

@@ -0,0 +1,29 @@
+:man_page: mongoc_oidc_callback_get_fn
+
+mongoc_oidc_callback_get_fn()
+=============================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  mongoc_oidc_callback_fn_t
+  mongoc_oidc_callback_get_fn (const mongoc_oidc_callback_t *callback);
+
+Return the stored pointer to the callback function.
+
+Parameters
+----------
+
+* ``callback``: a :symbol:`mongoc_oidc_callback_t`.
+
+Returns
+-------
+
+A :symbol:`mongoc_oidc_callback_fn_t`.
+
+.. seealso::
+
+  - :symbol:`mongoc_oidc_callback_t`
+  - :symbol:`mongoc_oidc_callback_fn_t`

src/libmongoc/doc/mongoc_oidc_callback_get_user_data.rst

@@ -0,0 +1,29 @@
+:man_page: mongoc_oidc_callback_get_user_data
+
+mongoc_oidc_callback_get_user_data()
+====================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void *
+  mongoc_oidc_callback_get_user_data (const mongoc_oidc_callback_t *callback);
+
+Return the stored pointer to user data.
+
+Parameters
+----------
+
+* ``callback``: a :symbol:`mongoc_oidc_callback_t`.
+
+Returns
+-------
+
+A pointer to user data or ``NULL``.
+
+.. seealso::
+
+  - :symbol:`mongoc_oidc_callback_t`
+  - :symbol:`mongoc_oidc_callback_set_user_data()`

src/libmongoc/doc/mongoc_oidc_callback_new.rst

@@ -0,0 +1,31 @@
+:man_page: mongoc_oidc_callback_new
+
+mongoc_oidc_callback_new()
+==========================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  mongoc_oidc_callback_t *
+  mongoc_oidc_callback_new (mongoc_oidc_callback_fn_t fn)
+
+Create a new :symbol:`mongoc_oidc_callback_t` object which stores the provided OIDC callback function.
+
+Equivalent to calling :symbol:`mongoc_oidc_callback_new_with_user_data()` with ``user_data`` set to ``NULL``.
+
+Parameters
+----------
+
+* ``fn``: a :symbol:`mongoc_oidc_callback_fn_t`. Must not be ``NULL``.
+
+Returns
+-------
+
+A new :symbol:`mongoc_oidc_callback_t` that must be freed with :symbol:`mongoc_oidc_callback_destroy()`, or ``NULL`` when an invalid argument was given.
+
+.. seealso::
+
+  - :symbol:`mongoc_oidc_callback_t`
+  - :symbol:`mongoc_oidc_callback_new_with_user_data`

src/libmongoc/doc/mongoc_oidc_callback_new_with_user_data.rst

@@ -0,0 +1,34 @@
+:man_page: mongoc_oidc_callback_new_with_user_data
+
+mongoc_oidc_callback_new_with_user_data()
+=========================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  mongoc_oidc_callback_t *
+  mongoc_oidc_callback_new_with_user_data (mongoc_oidc_callback_fn_t fn, void *user_data)
+
+Create a new :symbol:`mongoc_oidc_callback_t` object which stores the provided OIDC callback function and pointer to user data.
+
+.. warning::
+
+    The lifetime of the object pointed to by ``user_data`` is managed the user, not by :symbol:`mongoc_oidc_callback_t`!
+
+Parameters
+----------
+
+* ``fn``: a :symbol:`mongoc_oidc_callback_fn_t`. Must not be ``NULL``.
+* ``user_data``: a pointer to user data or ``NULL``.
+
+Returns
+-------
+
+A new :symbol:`mongoc_oidc_callback_t` that must be freed with :symbol:`mongoc_oidc_callback_destroy()`, or ``NULL`` when an invalid argument was given.
+
+.. seealso::
+
+  - :symbol:`mongoc_oidc_callback_t`
+  - :symbol:`mongoc_oidc_callback_new`

src/libmongoc/doc/mongoc_oidc_callback_params_cancel_with_timeout.rst

@@ -0,0 +1,33 @@
+:man_page: mongoc_oidc_callback_params_cancel_with_timeout
+
+mongoc_oidc_callback_params_cancel_with_timeout()
+=================================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  mongoc_oidc_credential_t *
+  mongoc_oidc_callback_params_cancel_with_timeout (mongoc_oidc_callback_params_t *params);
+
+Set the out parameter indicating cancellation of the callback function due to a timeout instead of an error.
+
+.. note::
+
+  If the callback function returns a not-null value, the value of this out parameter is ignored.
+
+Parameters
+----------
+
+* ``params``: a :symbol:`mongoc_oidc_callback_params_t`.
+
+Returns
+-------
+
+``NULL``.
+
+.. seealso::
+
+  - :symbol:`mongoc_oidc_callback_params_t`
+  - :symbol:`mongoc_oidc_callback_t`

src/libmongoc/doc/mongoc_oidc_callback_params_get_timeout.rst

@@ -0,0 +1,36 @@
+:man_page: mongoc_oidc_callback_params_get_timeout
+
+mongoc_oidc_callback_params_get_timeout()
+=========================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  const int64_t *
+  mongoc_oidc_callback_params_get_timeout (const mongoc_oidc_callback_params_t *params);
+
+Return a value comparable with :symbol:`bson_get_monotonic_time()` to determine when a timeout must occur.
+
+A ``NULL`` (unset) return value means "infinite" timeout.
+
+Parameters
+----------
+
+* ``params``: a :symbol:`mongoc_oidc_callback_params_t`.
+
+Returns
+-------
+
+A value comparable with :symbol:`bson_get_monotonic_time()`, or ``NULL``.
+
+Lifecycle
+---------
+
+The pointed-to ``int64_t`` is only valid for the duration of the invocation of the OIDC callback function.
+
+.. seealso::
+
+  - :symbol:`mongoc_oidc_callback_params_t`
+  - :symbol:`mongoc_oidc_callback_t`

src/libmongoc/doc/mongoc_oidc_callback_params_get_user_data.rst

@@ -0,0 +1,35 @@
+:man_page: mongoc_oidc_callback_params_get_user_data
+
+mongoc_oidc_callback_params_get_user_data()
+===========================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  void *
+  mongoc_oidc_callback_params_get_user_data (const mongoc_oidc_callback_params_t *params);
+
+Return the pointer to user data which was stored by an associated :symbol:`mongoc_oidc_callback_t` object.
+
+Parameters
+----------
+
+* ``params``: a :symbol:`mongoc_oidc_callback_params_t`.
+
+Returns
+-------
+
+A pointer to user data or ``NULL``.
+
+Lifecycle
+---------
+
+The lifetime of the object pointed to by ``user_data`` is managed the user.
+
+.. seealso::
+
+  - :symbol:`mongoc_oidc_callback_params_t`
+  - :symbol:`mongoc_oidc_callback_t`
+  - :symbol:`mongoc_oidc_callback_set_user_data()`

src/libmongoc/doc/mongoc_oidc_callback_params_get_username.rst

@@ -0,0 +1,35 @@
+:man_page: mongoc_oidc_callback_params_get_username
+
+mongoc_oidc_callback_params_get_username()
+==========================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  const char *
+  mongoc_oidc_callback_params_get_username (const mongoc_oidc_callback_params_t *params);
+
+Return the username component of the URI of an associated :symbol:`mongoc_client_t` or :symbol:`mongoc_client_pool_t` object.
+
+Parameters
+----------
+
+* ``params``: a :symbol:`mongoc_oidc_callback_params_t`.
+
+Returns
+-------
+
+A string which must not be modified or freed, or ``NULL``.
+
+Lifecycle
+---------
+
+The string is only valid for the duration of the invocation of the OIDC callback function.
+
+.. seealso::
+
+  - :symbol:`mongoc_oidc_callback_params_t`
+  - :symbol:`mongoc_oidc_callback_t`
+  - :symbol:`mongoc_uri_t`

src/libmongoc/doc/mongoc_oidc_callback_params_get_version.rst

@@ -0,0 +1,29 @@
+:man_page: mongoc_oidc_callback_params_get_version
+
+mongoc_oidc_callback_params_get_version()
+=========================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  int32_t
+  mongoc_oidc_callback_params_get_version (const mongoc_oidc_callback_params_t *params);
+
+Return the OIDC callback API version number.
+
+Parameters
+----------
+
+* ``params``: a :symbol:`mongoc_oidc_callback_params_t`.
+
+Returns
+-------
+
+A positive integer.
+
+.. seealso::
+
+  - :symbol:`mongoc_oidc_callback_params_t`
+  - :symbol:`mongoc_oidc_callback_t`