Skip to content

CXX-3235 add mongocxx::v1 forward headers and component files #1462

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Sep 25, 2025
Merged

CXX-3235 add mongocxx::v1 forward headers and component files #1462

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
d952843
CXX-3235 add mongocxx::v1 forward headers and component files
eramongodb Sep 15, 2025
38cb4e0
Merge remote-tracking branch 'upstream/master' into cxx-3235
eramongodb Sep 17, 2025
3a643b6
Merge remote-tracking branch 'upstream/master' into HEAD
eramongodb Sep 19, 2025
a11fb77
Add developer notes referencing relevant specifications
eramongodb Sep 19, 2025
17d401f
Rename: stable_api -> server_api
eramongodb Sep 19, 2025
e5ed97a
Add reference to mongoc APM docs
eramongodb Sep 19, 2025
5f594d4
Fix reference to In-Use Encryption options
eramongodb Sep 19, 2025
872bc34
Bulk write operations may be unordered
eramongodb Sep 19, 2025
ac52692
Refer to individual write operations without "bulk"
eramongodb Sep 19, 2025
5e93fad
Do not mix up DB commands with complex operations
eramongodb Sep 19, 2025
fec91da
Remove reference to CMAP spec for command*Events
eramongodb Sep 19, 2025
ce81449
Replace "command" -> "operation" for non-db-commands
eramongodb Sep 19, 2025
a9e0160
Fix doc typos
eramongodb Sep 19, 2025
5506725
Fix reference to TLS/SSL docs
eramongodb Sep 19, 2025
ac353e6
Fix incorrect include directive
eramongodb Sep 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions src/mongocxx/include/mongocxx/docs/v1.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,27 @@
/// @warning For internal use only!
///

///
/// @dir mongocxx/v1/events
/// Provide headers related to APM events.
///

///
/// @dir mongocxx/v1/gridfs
/// Provide headers related to GridFS.
///

///
/// @namespace mongocxx::v1
/// Declares entities whose ABI stability is guaranteed for documented symbols.
///

///
/// @namespace mongocxx::v1::gridfs
/// @copydoc mongocxx::gridfs
///

///
/// @namespace mongocxx::v1::events
/// @copydoc mongocxx::events
///
32 changes: 32 additions & 0 deletions src/mongocxx/include/mongocxx/v1/aggregate_options-fwd.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
// Copyright 2009-present MongoDB, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#pragma once

#include <mongocxx/v1/detail/prelude.hpp>

namespace mongocxx {
namespace v1 {

class aggregate_options;

} // namespace v1
} // namespace mongocxx

#include <mongocxx/v1/detail/postlude.hpp>

///
/// @file
/// Declares @ref mongocxx::v1::aggregate_options.
///
44 changes: 44 additions & 0 deletions src/mongocxx/include/mongocxx/v1/aggregate_options.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
// Copyright 2009-present MongoDB, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
Comment on lines +1 to +13
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we actually have guidance that putting a license header at the top of every single file is actually required? @kevinAlbs

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Per comments in DRIVERS-329:

The copyright notice (© MongoDB, Inc 2008-present.) goes in both source code and docs. [...] using the project inception year in all files is fine.

There is an open question in CDRIVER-5613 (which I filed back when working on CDRIVER-4044) whether it should really be "all files" or whether it can be reduced to a smaller subset:

Apache guidelines state, "It is also valuable to tag each of your source-code files in case they become detached from the LICENSE file." But this too doesn't clarify what source-code files should be considered at-risk of becoming detached from the LICENSE file, or in what manner they may become detached. Where should we draw the line on which source files require a license notice?

Quoting the REUSE Specification FAQ:

Then, for all files, edit the header to contain the following: [...] Marking all individual files with SPDX-License-Identifier tags goes a long way towards unambiguously communicating the license information of your project, but it helps to communicate the license information in natural language as well.

which also cites this article:

put [a license header] in every source code file and go check out (and follow) REUSE.software best practices, published by the FSFE.

My takeaway is that, at the very least, every file that is part of the repository should contain at least (1) the copyright notice and (2) a reference to the applicable software license (either as directed by the license or by using an SPDX license specifier). By default, the REUSE specification and related tool attempts to include a (minimal) license header in every source file (with fallback to x.license when x doesn't support a "header" syntax).


#pragma once

#include <mongocxx/v1/aggregate_options-fwd.hpp>

//

#include <mongocxx/v1/detail/prelude.hpp>

namespace mongocxx {
namespace v1 {

///
/// Options for an "aggregate" command.
///
/// @see
/// - [`aggregate` (database command) (MongoDB Manual)](https://www.mongodb.com/docs/manual/aggregation/)
///
/// @attention This feature is experimental! It is not ready for use!
///
class aggregate_options {};

} // namespace v1
} // namespace mongocxx

#include <mongocxx/v1/detail/postlude.hpp>

///
/// @file
/// Provides @ref mongocxx::v1::aggregate_options.
///
32 changes: 32 additions & 0 deletions src/mongocxx/include/mongocxx/v1/apm-fwd.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
// Copyright 2009-present MongoDB, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#pragma once

#include <mongocxx/v1/detail/prelude.hpp>

namespace mongocxx {
namespace v1 {

class apm;

} // namespace v1
} // namespace mongocxx

#include <mongocxx/v1/detail/postlude.hpp>

///
/// @file
/// Declares @ref mongocxx::v1::apm.
///
44 changes: 44 additions & 0 deletions src/mongocxx/include/mongocxx/v1/apm.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
// Copyright 2009-present MongoDB, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#pragma once

#include <mongocxx/v1/apm-fwd.hpp>

//

#include <mongocxx/v1/detail/prelude.hpp>

namespace mongocxx {
namespace v1 {

///
/// Options related to Application Performance Monitoring (APM) configuration.
///
/// @see
/// - [Application Performance Monitoring (mongoc)](https://mongoc.org/libmongoc/current/application-performance-monitoring.html)
/// - [Command Logging and Monitoring (MongoDB Specifications)](https://specifications.readthedocs.io/en/latest/command-logging-and-monitoring/command-logging-and-monitoring/)
/// - [SDAM Logging and Monitoring Specification (MongoDB Specifications)](https://specifications.readthedocs.io/en/latest/server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring/)
///
class apm {};

} // namespace v1
} // namespace mongocxx

#include <mongocxx/v1/detail/postlude.hpp>

///
/// @file
/// Provides @ref mongocxx::v1::apm.
///
32 changes: 32 additions & 0 deletions src/mongocxx/include/mongocxx/v1/auto_encryption-fwd.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
// Copyright 2009-present MongoDB, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#pragma once

#include <mongocxx/v1/detail/prelude.hpp>

namespace mongocxx {
namespace v1 {

class auto_encryption;

} // namespace v1
} // namespace mongocxx

#include <mongocxx/v1/detail/postlude.hpp>

///
/// @file
/// Declares @ref mongocxx::v1::auto_encryption.
///
43 changes: 43 additions & 0 deletions src/mongocxx/include/mongocxx/v1/auto_encryption.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
// Copyright 2009-present MongoDB, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#pragma once

#include <mongocxx/v1/auto_encryption-fwd.hpp>

//

#include <mongocxx/v1/detail/prelude.hpp>

namespace mongocxx {
namespace v1 {

///
/// Options related In-Use Encryption configuration.
///
/// @see
/// - [MongoClient Options for Queryable Encryption (MongoDB Manual)](https://www.mongodb.com/docs/manual/core/queryable-encryption/reference/qe-options-clients/)
/// - [MongoClient Options for CSFLE](https://www.mongodb.com/docs/manual/core/csfle/reference/csfle-options-clients/)
///
class auto_encryption {};

} // namespace v1
} // namespace mongocxx

#include <mongocxx/v1/detail/postlude.hpp>

///
/// @file
/// Provides @ref mongocxx::v1::auto_encryption.
///
32 changes: 32 additions & 0 deletions src/mongocxx/include/mongocxx/v1/bulk_write-fwd.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
// Copyright 2009-present MongoDB, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#pragma once

#include <mongocxx/v1/detail/prelude.hpp>

namespace mongocxx {
namespace v1 {

class bulk_write;

} // namespace v1
} // namespace mongocxx

#include <mongocxx/v1/detail/postlude.hpp>

///
/// @file
/// Declares entities related to bulk write operations.
///
Loading