Description

The MongoDB Rust driver team is pleased to announce the v2.0.0-beta release of the driver. This release contains a number of breaking changes, API improvements, new features, and bug fixes. We do not intend to make any further breaking changes before the v2.0.0 stable release, though we may do so if needed.

Highlighted breaking changes

The following sections detail some of the more important breaking changes included in this release. For a full list of changes, see the Full Release Notes section.

Update version of `bson` to `v2.0.0-beta`

The exported version of bson was updated to v2.0.0-beta, which includes its own set of breaking changes. Check out the bson release notes for more information.

Ensure API meets the Rust API Guidelines (RUST-765)

There is a community-maintained list of API guidelines that every stable Rust library is recommended to meet. The driver's current API wasn't conforming to these guidelines exactly, so a number of improvements were made to ensure that it does. Here we highlight a few of the more important changes made in this effort.

Various error API improvements (RUST-739, RUST-765)

Several improvements were made to the ErrorKind enum according to the guidelines to provide a more consistent and stable API:

The variants no longer wrap error types from unstable dependencies (C-STABLE)
The variant are named more consistently (C-WORD-ORDER)
- Drop redundant Error suffix from each variant name
Redundant error variants were consolidated

The total list of breaking changes is as follows:

All error variants dropped the "Error" suffix (e.g. ErrorKind::ServerSelectionError => ErrorKind::ServerSelection)
ErrorKind::ArgumentError => ErrorKind::InvalidArgument
- ErrorKind::InvalidHostname => removed, consolidated into ErrorKind::InvalidArgument
ErrorKind::BsonDecode => ErrorKind::BsonDeserialization
ErrorKind::BsonEncode => ErrorKind::BsonSerialization
ErrorKind::ResponseError => ErrorKind::InvalidResponse
ErrorKind::DnsResolve(trust_dns_resolver::error::ResolveError) => ErrorKind::DnsResolve { message: String }
- ErrorKind::InvalidDnsName => removed, consolidated into ErrorKind::DnsResolve
- ErrorKind::NoDnsResults => removed, consolidated into ErrorKind::DnsResolve
- ErrorKind::SrvLookupError => removed, consolidated into ErrorKind::DnsResolve
- ErrorKind::TxtLookupError => removed, consolidated into ErrorKind::DnsResolve
ErrorKind::RustlsConfig(rustls::TLSerror) => ErrorKind::InvalidTlsConfig { message: String }
- ErrorKind::ParseError => removed, consolidated into ErrorKind::InvalidTlsConfig
ErrorKind::WaitQueueTimeoutError => removed, the wait_queue_timeout option is no longer supported (RUST-757)
ErrorKind::OperationError => removed, consolidated into ErrorKind::InvalidResponse and ErrorKind::Internal as appropriate

Stabilize or eliminate public dependencies on unstable types (C-STABLE, RUST-739)

The driver included types from a number of unstable (pre-1.0) dependencies in its public API, which presented a problem for the stability of the driver itself. tokio was one such example of this, which is why when it went 1.0, the driver needed a 2.0 release. In an effort to ensure that the driver will no longer be subject to the semver breaks of unstable dependencies and can stay on 2.0 for the foreseeable future, the public dependencies on unstable types were removed altogether or stabilized such that they will always be present.

Here are the notable changes made as part of that:

Cursor types now implement the Stream trait from futures-core rather than futures.
- futures-core will be moving directly to 1.0 next, whereas futures may have several semver-incompatible versions.
- The 2.0 version of the driver will continue to depend on futures-core 0.3 (current release), even after futures-core 1.0 is released and/or the Stream trait is included in the standard library. The cursor types will also implement each of the Stream traits from futures-core 1.0 and std as necessary, and users can depend on and import the one they wish to use.
- It's possible no changes will need to be made in the driver to transition to std::Stream. See (rust-lang/futures-rs#2362)
ErrorKind variants that wrapped unstable errors were removed or refactored (see above)
Introduced a ResolverConfig type that opaquely wraps a trust_dns_resolver::ResolverConfig
TlsOptions::into_rustls_config was removed from the public API

Wrap `Error::kind` in a `Box` (RUST-742)

In v2.0.0-alpha.1, we removed the Arc wrapper around Error::kind in order to improve the ergonomics of our Error type. The ErrorKind enum is quite large, however, which in turn made Error and mongodb::error::Result large too. In order to balance the ergonomics improvements of having an owned Error::kind with the small size of an Arc wrapped Error::kind, we decided to wrap it in a Box. This reduces the size of Error greatly while also allowing users to get an owned ErrorKind if they wish via the * operator.

Options builders Improvements (RUST-615)

The driver uses the typed-builder crate to generate the builders for its various options structs (e.g. ClientOptions::builder()). In this release, we updated its version to 0.9.0 and with that, introduced the following improvements:

the builder methods for Option<T> fields now accept T instead of impl Into<Option<T>>
- previously, every method required impl Into<T>, so fields that were options required the explicit Some(...) to enable type inference on the interior type.
- As part of this, the builder methods for T also just accept T, rather than Into<T>, allowing for type inference
incomplete .build() and repeated setters will now issue improved errors via deprecation warnings. See the typed-builder documentation for more information.

// old
let options = ClientOptions::builder()
    .hosts(vec![StreamAddress {
        hostname: "localhost".to_string(),
        port: Some(27017),
    }])
    .read_concern(Some(ReadConcernLevel::Local.into()))
    .build();
                             
// new
let options = ClientOptions::builder()
    .hosts(vec![ServerAddress::Tcp {
        host: "localhost".to_string(),
        port: Some(27017),
    }])
    .read_concern(ReadConcernLevel::Local.into())
    .build();

Accept `impl Borrow<T>` in various CRUD methods (RUST-754)

Prior to this release, methods such as Collection::insert_one accepted an owned T despite not actually requiring ownership of the value. This could lead to wasteful clones that hurt performance. As an improvement, these methods were updated to accept impl Borrow<T>, which means either owned or borrowed types may be passed in.

Return types that implement `Deserialize` from `Client::list_databases` and `Database::list_collections` (RUST-740)

These methods used to return Vec<Document> and Cursor<Document> respectively, both of which do not take advantage of the fact that the format of the returned documents is known and stable. To improve on that, these methods were updated to return Vec<DatabaseSpecification> and Cursor<CollectionSpecification> instead, which should make the responses more ergonomic to work with.

Refactor `StreamAddress` (RUST-760)

StreamAddress was used to specify via the ClientOptions which hosts the driver was to connect to. This type was inaccurate though, since it usually contains DNS names that get resolved to one or more socket addresses rather than the socket address itself. Furthermore, in the future the driver may want to support other ways of connecting to MongoDB servers, such as Unix Domain Sockets, which would further make the StreamAddress name confusing. To improve the accuracy of the type's name enable it to be more easily extended in the future, it was refactored to the following type:

#[non_exhaustive]
pub enum ServerAddress {
    Tcp { host: String, port: Option<u16> }
}

This is similar to the equivalent types provided by the tokio-postgres and redis crates.

Note: this change only affects users that construct their own ClientOptions structs (as opposed to parsing them from a connection string) or consumers of CMAP events.

Full Release Notes

New features

RUST-808 Upgrade bson to 2.0.0-beta (breaking)
RUST-615 Upgrade typed-builder to 0.9.0 (breaking)
RUST-738 Implement Clone on BSON error types (breaking)
RUST-740 Return Deserialize types from list_databases and list_collections (breaking)
RUST-754 Accept references in insert and replace methods (breaking)
RUST-796 Provide easy way to reborrow session in between cursor iterations (breaking)

Improvements

RUST-739 Don't re-export types from unstable dependencies (breaking)
RUST-742 Reduce size of Error and ErrorKind (breaking)
RUST-760 Refactor StreamAddress to ServerAddress enum (breaking)
RUST-757 Remove wait_queue_timeout (breaking)
RUST-761 Rename CreateCollectionOptions::validation to CreateCollectionOptions::validator (breaking)
RUST-764 Use unsigned integers for values that should always be positive (breaking)
RUST-765 Ensure API follows Rust API Guidelines (breaking)
RUST-784 Mark WriteConcern::validate as pub(crate) (breaking)
RUST-786 Update collation options to use custom types rather than integers and strings (breaking)
RUST-788 Accept impl AsRef<str> instead of &str (breaking)
RUST-791 Accept PathBuf instead of String for paths in options (breaking)

Bug fixes

RUST-591 ConnectionPoolOptions is used for event monitoring and pool internals (breaking)
RUST-759 DropCollectionOptions should skip serializing fields with a None value

mongodb 2.0.0-beta v2.0.0-beta on Rust Cargo