v2.0.0-beta

Description

The MongoDB Rust driver team is pleased to announce the v2.0.0-beta release of the bson crate in preparation for the 2.0.0 stable release. This release contains a number of breaking changes, API improvements, new features, and bug fixes, and it will be included in v2.0.0-beta of the driver. It was not included in the previous driver alpha releases, however.

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.

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 crate's existing 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.

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

bson included types from a number of unstable (pre-1.0) dependencies in its public API, which presented a problem for the stability of the library itself. In an effort to ensure that bson 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:

• Bson::DateTime(chrono::DateTime<Utc>) => Bson::DateTime(bson::DateTime)
  • Instead of directly including a DateTime from chrono (which is currently 0.4), the variant now wraps the bson::DateTime newtype defined within bson. This way the dependency on chrono can be updated to new semver breaking versions without having to update its major version.
  • To ease in the construction and usage of this type, From<chrono_0_4::DateTime> is implemented for bson::DateTime, and From<bson::DateTime> is implemented for chrono_0_4::DateTime. As new semver breaking versions of chrono are released, these From implementations will continue to exist, and in new minor versions of bson, new From implementations for the new versions of chrono will be added while continuing to maintain the old ones. This is achieved by having bson depend on multiple semver-incompatible versions of chrono. This way, users of chrono 0.4 will not have their code broken when updating bson versions, but users of chrono 0.5+ will also be able to easily work with bson::DateTime.
• struct Datetime(pub chrono::DateTime) => struct DateTime { /* private fields */ }
  • Same reasoning applies as for the above bullet
• Document::get_datetime returns a ValueAccessResult of &bson::DateTime instead of &chrono::DateTime
• Bson::as_datetime returns an Option of &bson::DateTime instead of &chrono::DateTime
• ObjectId::timestamp returns a crate::DateTime instead of chrono::DateTime
• oid::Error no longer wraps hex::FromHexError (the hex crate is 0.4), see below for details.
• The serde_helpers that interface with unstable dependencies are versioned
  • e.g. chrono_datetime_as_bson_datetime => chrono_0_4_datetime_as_bson_datetime

Accept impl AsRef<str> in Document methods (C-GENERIC, RUST-765)

The methods on Document that accepted keys previously accepted them as &str. They were updated to accept impl AsRef<str> instead to allow other string-like types to be used for key lookup, such as String.

Use more standard conversion constructors for ObjectId (C-CONV-TRAITS, C-CTOR, RUST-789)

ObjectId previously had three constructors: new, with_bytes, and with_string. The latter two were a bit inconsistent with the functions they performed and with similar constructors for related types in the Rust ecosystem. To remedy this, the constructors were updated to match uuid::Uuid's constructor API:

• ObjectId::with_bytes => const ObjectId::from_bytes
• ObjectId::with_string => ObjectId::parse_str

Error naming improvements (C-WORD-ORDER, C-STABLE)

Some error variants were renamed or restructured to be clearer or more informative. A complete summary of the changes are as follows:

• bson::de::Error:
  • IoError => Io
  • FromUtf8Error => InvalidUtf8String
  • SyntaxError => removed, consolidated into DeserializationError.
  • InvalidTimestamp(i64) => InvalidDateTime { key: String, datetime: i64 }
• bson::ser::Error:
  • IoError => Io
  • InvalidMapKeyType { key: Bson } => InvalidDocumentKey(Bson)
  • UnsupportedUnsignedType => UnsupportedUnsignedInteger(u64)
  • UnsignedTypesValueExceededRange => UnsignedIntegerExceededRange(u64)
• oid::Error:
  • ArgumentError => removed
  • FromHexError => removed, replaced by the new InvalidHexStringCharacter and InvalidHexStringLength variants

Other miscellaneous changes

There were some other smaller breaking changes made as part of this as well:

• Ensure public structs are future proof by marking them as non_exhaustive (C-STRUCT-PRIVATE)
• document::DocumentIterator and document::DocumentIntoIterator renamed to document::Iter and document::IntoIter (C-ITER-TY)
• Deprecated Decimal128 conversion constructors removed (C-CONV)

Implement Clone on all error types (RUST-738)

Previously many of the error types did not implement Clone, partially because many of them wrapped std::io::Error. Not implementing Clone made these errors difficult to work with, since they needed to be wrapped in an Arc or Rc in order to be passed around without transferring ownership. To avoid that requirement, we implemented Clone on all of the error types in bson. For the errors that wrapped std::io::Error, this required wrapping the wrapped std::io::Errors in Arcs.

Implement Copy for ObjectId (RUST-680)

Since ObjectId is just a wrapper around a 12-byte array, it is cheap to copy and therefore ought to implement Copy. As part of this, helpers on Document and Bson were updated to return owned ObjectIds instead of references to them.

Thanks to @jcdyer for contributing this change!

Replace linked-hash-map with indexmap (RUST-283)

The dependency on the now unmaintained linked-hash-map was replaced with the more up-to-date indexmap. While this isn't a breaking change on its own, the Entry API of Document was updated to match both that of std::collections::HashMap and indexmap in a breaking way.

Replace compat::u2f with serde helpers (RUST-756)

The compat::u2f module has long existed to provide a way to serialize unsigned integers as BSON doubles, but it is inconsistent with the API we provide for these kinds of conversions today, namely the serde_helpers functions and modules. In order to present a more consistent API, the compat::u2f module was removed and most of its conversion helpers were rewritten as serde_helpers.

Full Release Notes

New Features

• RUST-680 Implement Copy for ObjectId (breaking)
• RUST-747 Add serde helper to deserialize hex string from ObjectId (thanks @moka491!)
• RUST-738 Implement Clone on BSON error types (breaking)

Bugfixes

• RUST-713 Fix underflow on BSON array and binary deserialization (thanks @gperinazzo and @5225225!)
• RUST-798 Return error instead of silently loses precision when serializing sub-millisecond precision datetime to BSON

Improvements

• RUST-709 Update decimal dependency to 2.1.0
• RUST-283 Replace linked-hash-map with indexmap (breaking)
• RUST-711 Use imports_granularity=Crate in rustfmt config
• RUST-756 Replace compat::u2f with serde helpers (breaking)
• RUST-739 Don't re-export types from unstable dependencies (breaking)
• RUST-789 Standardize on ObjectId conversion constructors (breaking)
• RUST-788 Accept impl AsRef<str> instead of &str in Document methods (breaking)
• RUST-765 Ensure API follows Rust API Guidelines (breaking)