CXX-3082 Add comprehensive examples (mongocxx, Part 2)

[eramongodb]

Summary

Resolves CXX-3082. Followup to #1216. Verified by this patch.

Adds examples for the remaining items listed in the description of #1216:

• Databases Error Handling (that are not operation exceptions)
• Collections Error Handling (that are not operation exceptions)
• Change Streams
• Sessions
• Transactions (as part of Sessions)

Additionally adds examples for index views (not to be confused with Atlas Search Indexes or Queryable Encryption Range Indexes) as part of Collection examples.

Deferred / Out of Scope

The following headers do not have an API example due to redundancy (their usage may follow a similar pattern to an existing representative example). Users may reference the API documentation to learn how to use said interfaces instead.

• mongocxx/v_noabi/mongocxx/hint.hpp
• mongocxx/v_noabi/mongocxx/model/delete_many.hpp
• mongocxx/v_noabi/mongocxx/model/delete_one.hpp
• mongocxx/v_noabi/mongocxx/model/replace_one.hpp
• mongocxx/v_noabi/mongocxx/model/update_many.hpp

The following headers do not have an API example due to deliberately being excluded from the current scope of work (their implementation requires significant effort and complexity, or an example of its usage is not expected to be necessary). These may be revisited in the future.

• Atlas
  • mongocxx/v_noabi/mongocxx/search_index_model.hpp
  • mongocxx/v_noabi/mongocxx/search_index_view.hpp
• GridFS
  • mongocxx/v_noabi/mongocxx/gridfs/bucket.hpp
  • mongocxx/v_noabi/mongocxx/gridfs/downloader.hpp
  • mongocxx/v_noabi/mongocxx/gridfs/uploader.hpp
  • mongocxx/v_noabi/mongocxx/options/gridfs/bucket.hpp
  • mongocxx/v_noabi/mongocxx/options/gridfs/upload.hpp
  • mongocxx/v_noabi/mongocxx/result/gridfs/upload.hpp
• CSFLE
  • mongocxx/v_noabi/mongocxx/client_encryption.hpp
  • mongocxx/v_noabi/mongocxx/options/client_encryption.hpp
  • mongocxx/v_noabi/mongocxx/options/data_key.hpp
  • mongocxx/v_noabi/mongocxx/options/encrypt.hpp
  • mongocxx/v_noabi/mongocxx/options/range.hpp
  • mongocxx/v_noabi/mongocxx/options/rewrap_many_datakey.hpp
  • mongocxx/v_noabi/mongocxx/result/rewrap_many_datakey.hpp

The following headers do not have an API example due to the expectation of eventual deprecation-and-removal, to encourage use of alternative patterns, or because they are simply unused. (In particular, concerning CXX-834 for the current exception class hierarchy.)

• mongocxx/v_noabi/mongocxx/exception/authentication_exception.hpp
• mongocxx/v_noabi/mongocxx/exception/bulk_write_exception.hpp
• mongocxx/v_noabi/mongocxx/exception/gridfs_exception.hpp
• mongocxx/v_noabi/mongocxx/exception/logic_error.hpp
• mongocxx/v_noabi/mongocxx/exception/query_exception.hpp
• mongocxx/v_noabi/mongocxx/exception/write_exception.hpp
• mongocxx/v_noabi/mongocxx/validation_criteria.hpp

In light of CXX-834, mongocxx::exception is used/encouraged as much as possible, with mongocxx::operation_exception used only when access to raw server error information is required. All other exception classes are deliberately not referenced in the API examples.

Note

Error handling for exceptions (that are not operation_exception) thrown by specific interfaces which are considered redundant or out-of-scope by this PR are deferred to API documentation. These examples are intended to be comprehensive, but not exhaustive.

API Examples Runner

The runner now supports disabling use of fork() on invocation even if the feature is enabled. This flag (combined with --jobs 1) is expected to help improve the debugging experience of API examples (execution on a single process and a single thread).

DB Lock

The DB Lock class learned to use "majority" read/write concern when dropping the collection to better support reliability and consistency of examples when run against replica sets and sharded clusters. The class also learned to avoid violating database name length limitations by clipping the front of the example component name (used as a unique database name in many examples) to remain within 63 characters.

Specific Workarounds

Several examples require extra considerations to remain compatible with server topologies and/or execution environments. These include:

• using mongocryptdURI + mongocryptdSpawnArgs in the auto encryption options example to avoid the spawned mongocryptd instance from stepping over a port (27020) in use by a sharded cluster (mongos on 27017 and 27018, a config server on 27019, and at least one mongod on 27020 through 27020 + N).
• examples which use transactions have an exception handler to account for multi-document transaction support with sharded clusters requiring MongoDB server 4.2+.

[eramongodb]

Per suggestions in this comment, added support for --filter and --verbose flags, which may be used as follows:

./runner --verbose 0 # Default: no verbose.
./runner --verbose 1 # Enable listing components to be executed.

# List and run only components with "bsoncxx" in its name.
./runner --verbose 1 --filter bsoncxx

# List and run only components with "bsoncxx" AND "json" in its name.
./runner --verbose 1 --filter bsoncxx --filter json

These updates revealed some additional areas for improvement:

• Only the "normal" and "forking" components were being shuffled. Extended shuffling to live server components as well.
• Added an alphabetic sort prior to shuffle to ensure deterministic shuffling regardless of static object initialization ordering (by which components are registered).

[kevinAlbs]

LGTM!