CDRIVER-6044 Text search explicit encryption API and prose tests

[mdb-ad]

No description provided.

[kevinAlbs]

See the make-docs task for docs warnings causing the task to fail:

mongoc_encrypt_text_opts_t.rst: WARNING: document isn't included in any toctree

Docs can be built with instructions from CONTRIBUTING.md:

uv run --frozen --with 'sphinx-autobuild' sphinx-autobuild -b html src/libmongoc/doc/ src/libmongoc/doc/html --re-ignore ".*.pickle" --re-ignore ".*.doctree" -j auto

[kevinAlbs]

Suggested change

	} mc_optional_int32_t;
	} mcd_optional_int32_t;

Suggest giving this a different name than the mc_optional_int32_t symbol in libmongocrypt. The PHP driver builds the C driver and libmongocrypt side-by-side, so this may cause redefinition errors. Quoting MONGOCRYPT-845:

libmongoc, libbson, and libmongocrypt are all compiled statically into the PHP extension

[kevinAlbs]

Suggested change

	} mc_optional_bool;
	} mcd_optional_bool;

Alternatively: use the existing mongoc_optional_t (which I would rather name mongoc_optional_bool_t, but it is a public type).

[kevinAlbs]

On this function and other setters, use const since argument is only copied:

Suggested change

	mongoc_encrypt_text_opts_set_prefix(mongoc_encrypt_text_opts_t *opts, mongoc_encrypt_text_prefix_opts_t *popts)
	mongoc_encrypt_text_opts_set_prefix(mongoc_encrypt_text_opts_t *opts, const mongoc_encrypt_text_prefix_opts_t *popts)

[kevinAlbs]

Suggested change

	BSON_ASSERT_PARAM(opts);
	BSON_ASSERT_PARAM(opts);
	BSON_ASSERT_PARAM(text_opts);

[kevinAlbs]

Suggest avoiding defining prefix/suffix/substring as a typedef of the same struct: _encrypt_text_per_index_opts_t. I would rather avoid exposing the same struct is used for all three in public API. Future options might make these prefix/suffix/substring no longer be the same.

Consider instead:

typedef struct _mongoc_encrypt_text_prefix_opts_t mongoc_encrypt_text_prefix_opts_t;
typedef struct _mongoc_encrypt_text_suffix_opts_t mongoc_encrypt_text_suffix_opts_t;
typedef struct _mongoc_encrypt_text_substring_opts_t mongoc_encrypt_text_substring_opts_t;

Internally, share the same definition for convenience:

// In mongoc-client-side-encryption.c:

struct _encrypt_text_per_index_opts_t {
   mc_optional_int32_t str_max_length;
   mc_optional_int32_t str_max_query_length;
   mc_optional_int32_t str_min_query_length;
};

struct _mongoc_encrypt_text_prefix_opts_t {
   struct _encrypt_text_per_index_opts_t per_index_opts;
};

struct _mongoc_encrypt_text_suffix_opts_t {
   struct _encrypt_text_per_index_opts_t per_index_opts;
};

struct _mongoc_encrypt_text_substring_opts_t {
   struct _encrypt_text_per_index_opts_t per_index_opts;
};

[kevinAlbs]

Suggested change

	mongoc_client_encryption_encrypt_opts_set_query_type(eo, MONGOC_ENCRYPT_QUERY_TYPE_PREFIXPREVIEW);
	mongoc_client_encryption_encrypt_opts_set_query_type(eo, MONGOC_ENCRYPT_QUERY_TYPE_SUBSTRINGPREVIEW);