v2.1.0-beta

Description

The MongoDB Rust driver team is pleased to announce the v2.1.0-beta release of the bson crate. This release is a preview of the upcoming v2.1.0 release, which will be functionally the same but may contain fixes for any bugs identified in this beta.

Highlighted changes

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

Better Uuid ergonomics (RUST-819, RUST-465, RUST-1024)

Working with UUIDs in BSON is a bit of a pain point, since the widely used Uuid type from the uuid crate doesn't serialize to or from BSON UUIDs (i.e. Binary with subtype 4) out of the box. To address this, we introduced a bson::Uuid type, which serializes as a BSON UUID when using bson::to_bson or bson::to_slice and uses uuid::Uuid's Serialize implementation for other formats.

Additionally, we implemented the UUID driver specification, which enables easy conversion between Binary and bson::Uuid. It also adds support for handling BSON UUIDs that may have been serialized using the legacy format from one of the other MongoDB drivers (Python, Java, or C#).

Lastly, we introduced support for using the serde_with crate to serialize uuid::Uuids to BSON. This requires the usage of the serde_with and uuid-0_8 feature flags. See the next section for more details.

serde_with integration (RUST-1024)

As mentioned in the previous section, we've added optional support for the serde_with crate via the serde_with feature flag. Right now, this allows for serialization of chrono::DateTime as bson::DateTime (with the chrono-0_4 feature flag) and uuid::Uuid as bson::Uuid (with the uuid-0_8 feature flag). The main improvement of serde_with annotations over the existing serde helpers is that they also work when the Uuid or DateTime type is nested, such as in an Option.

#[serde_with::serde_as]
#[derive(Serialize, Deserialize, Debug)]
struct MyData {
    #[serde_as(as = "Option<bson::Uuid>")]
    uuid: Option<uuid::Uuid>,

    #[serde_as(as = "Option<bson::DateTime>")]
    dt: Option<chrono::DateTime<chrono::Utc>>,
}

let val = MyData {
    uuid: Some(uuid::Uuid::new_v4()),
    dt: chrono::Utc::now().into(),
};

// prints { "uuid": Binary(0x4, mMKbFkXEQMeLnfSNY+/NMg==), "dt": DateTime("2021-11-12 21:14:15.385 UTC") }
println!("{}", bson::to_bson(&val)?);

Support configuring Serializer and Deserializer to be not human-readable (RUST-1022)

Serializer and Deserializer, which are used in bson::(to|from)_(bson|document), have never implemented the is_human_readable requirement from their respective serde traits, meaning they default to true. The raw serializer and deserializer, which are used in bson::to_vec and bson::from_slice, do report as non-human readable though. The unfortunate result of this inconsistency is that types that change their serialized format depending on whether the (de)serializer is human readable or not may produce different BSON depending on whether to_bson or to_vec are used. To help address this issue, this release includes support for configuring Serializer and Deserializer to report themselves as not human readable.

#[derive(Debug, Deserialize, Serialize)]
struct MyData {
    a: String,
}

let data = MyData { a: "ok".to_string() };
let options = SerializerOptions::builder().human_readable(false).build();
let bson = bson::to_bson_with_options(&data, options)?;

let options = DeserializerOptions::builder().human_readable(false).build();
let rt_data: MyData = bson::from_bson_with_options(bson, options)?;

Full Release Notes

New Features

• RUST-465 Create a UUID wrapper type for serialization to / deserialization from BSON binary (#314)
• RUST-977 Support parsing bson::DateTime from RFC 3339 formatting string even without chrono feature flag (#317)
• RUST-1022 Introduce way to serialize to / deserialize from Bson with is_human_readable = false (#321)
• RUST-1024 Add serde_with integration for composable serde helpers (#323)
• RUST-787 Implement Display for all BSON types (#305)
• RUST-966 Add BSON Binary subtype 7 (#315)

Improvements

• Remove time transitive dependency and clock feature flag from chrono (#316)
  • Thanks @roccodev!

Bugfixes

• RUST-1107 Fix array relaxed extended JSON (#325) (thanks @pacifistes!)

v2.0.0

Description

The MongoDB Rust driver team is pleased to announce the v2.0.0 release of the bson crate. This release is the culmination of several months of work, and it contains a number of new features, API improvements, and bug fixes. This release will be included in v2.0.0 of the driver. It is intended that this release will be very stable and that bson will not have another major release for quite a long time.

Note that the new minimum supported Rust version (MSRV) is now 1.48.0.

Highlighted changes

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

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 gated behind feature flags.

Here are the notable changes made as part of that:

• Bson::DateTime(chrono::DateTime<Utc>) => Bson::DateTime(bson::DateTime), struct Datetime(pub chrono::DateTime) => struct DateTime { /* private fields */ }
  • Instead of directly including a DateTime from chrono (which is currently 0.4) in the Bson enum, the variant now wraps the bson::DateTime newtype defined within bson, and that newtype also no longer wraps a chrono::DateTime. This way the dependency on chrono can be updated to new semver breaking versions without having to update bson's major version.
  • To ease in the construction and usage of the newtype from chrono::DateTime, the chrono-0_4 feature flag can be enabled, which includes a From<chrono::DateTime> implementation for bson::DateTime and a From<bson::DateTime> implementation for chrono::DateTime, as well as some serde helpers.
• 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 Uuid serde helpers, as well as From<Uuid> implementations for Bson and Binary, are now gated behind the uuid-0_8 feature flag.

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 => removed
  • 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)

Enable the u2i behavior by default (RUST-968)

In the 1.x version of bson, unsigned integers could not be serialized to BSON by default, but the u2i feature flag could be enabled to allow them to be serialized by automatically converting them to signed integers. After some investigation, it was determined that this u2i behavior was more consistent with the behavior of BSON libraries in other languages with unsigned integers, so bson now exhibits it by default, and the u2i feature flag was removed.

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.

Remove the decimal128 feature flag (RUST-960, #287)

It was determined that the BSON serialization format that was used when the experimental decimal128 feature flag was enabled did not match the format expected by the database or other MongoDB tools and drivers. Because of this, the feature flag has been removed, as there was no way to use it correctly. See #282 for more details.

If you were relying on this feature flag or are just interested in a complete decimal128 implementation, please let us know on #53.

Support for serialization to and deserialization from BSON bytes (RUST-870, RUST-871, #276, #279)

This release adds support for direct serialization to and deserialization from BSON bytes via bson::to_vec and bson::from_slice / bson::from_reader, eliminating the need to go through Document when converting between Rust data types and BSON bytes. This can enable significant performance improvements in certain circumstances; most notably, this will greatly improve the performance of the MongoDB driver, which in 2.0.0 will begin leveraging this functionality.

Properly produce and ingest RFC 3339 (ISO 8601) datetimes in serde helpers (RUST-825)

The iso_string_as_bson_datetime and bson_datetime_as_iso_string serde helpers were not producing or only accepting valid ISO 8601 strings. This has been fixed, and the helpers have been renamed to rfc3339_string_as_bson_datetime and bson_datetime_as_rfc3339_string to more accurately reflect the standard they conform to.

Introduce serde helpers for legacy UUID formats (RUST-687)

The Python, Java, and C# drivers all used to serialize UUIDs with different legacy formats, none of which were supported by the existing UUID serde helper. To add support for serializing and deserializing these UUIDs, new serde helpers were introduced for each of the legacy formats. These helpers are also gated behind the "uuid-0_8" feature flag.
...

v2.0.0-beta.3

Description

The MongoDB Rust driver team is pleased to announce the v2.0.0-beta.3 release of the bson crate. This is the fourth beta release in preparation for the 2.0.0 stable release, and it contains a few improvements and bug fixes that were not included in the previous betas. This release will be included in v2.0.0-beta.3 of the driver. As with the previous beta releases, we do not intend to make any further breaking changes before v2.0.0, but we may do so in another beta if any issues arise before then.

Highlighted changes

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

Remove the decimal128 feature flag (RUST-960, #287)

It was determined that the BSON serialization format that was used when the experimental decimal128 feature flag was enabled did not match the format expected by the database or other MongoDB tools and drivers. Because of this, the feature flag has been removed, as there was no way to use it correctly. See #282 for more details.

If you were relying on this feature flag or are just interested in a complete decimal128 implementation, please let us know on #53.

Support for serialization to and deserialization from BSON bytes (RUST-870, RUST-871, #276, #279)

This release adds support for direct serialization to and deserialization from BSON bytes via bson::to_vec and bson::from_slice / bson::from_reader, eliminating the need to go through Document when converting between Rust data types and BSON bytes. This can enable significant performance improvements in certain circumstances; most notably, this will greatly improve the performance of the MongoDB driver, which in 2.0.0-beta.3 will begin leveraging this functionality.

Full Release Notes

Bugfixes

• RUST-884 Support deserializing DateTimes between the year 10,000 and 99,999
• RUST-942 Generate 5 random bytes instead of 3 for ObjectIds (#284)

New Features

• RUST-688 Support for borrowed deserialization (#276)
• RUST-870 Support deserializing directly from raw BSON (#276)
• RUST-871 Support serializing directly to BSON bytes (#279)

Improvements

• RUST-889 Avoid going through hex string when deserializing ObjectId from raw bytes (#287)
  • Thanks @univerz for the POC for this!
• RUST-960 Remove decimal128 feature flag and functionality (breaking)
• RUST-882 Remove lossy From<u64> impl for Bson (#280) (breaking)

v1.2.3

Description

The MongoDB Rust driver team is pleased to announce the 1.2.3 release of the bson crate. This release includes a number of important bug fixes.

Highlighted changes

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

Deprecate the decimal128 feature flag (RUST-960, #286)

It was determined that the BSON serialization format that is used when the experimental decimal128 feature flag is enabled does not match the format expected by the database or other MongoDB tools and drivers. Because of this, it is not recommended for use and has been deprecated, and the flag will be removed altogether in 2.0.0. See #282 for more details.

If you are relying on this feature flag or are just interested in a complete decimal128 implementation, please let us know on #53.

Full Release Notes

Bug

• RUST-755 Use zeroed rather than uninitialized memory for decimal128 deserialization (#263)
  • Thanks for reporting @5225225!
• RUST-880 Fix crash when deserializing/serializing Document that contains decimal128 (#285)
• RUST-882 Fix or improve lossy From unsigned integer impls for Bson (#281)
• RUST-942 Properly generate 5 random bytes instead of 3 for ObjectIds (#286)

Improvement

• RUST-960 Deprecate decimal128 feature flag (#288)

v2.0.0-beta.2

Description

The MongoDB Rust driver team is pleased to announce the v2.0.0-beta.2 release of the bson crate. This is the third beta release in preparation for the 2.0.0 stable release, and it contains a few minor improvements and bug fixes that were not included in the first or second betas. This release will be included in v2.0.0-beta.2 of the driver. As with the previous beta releases, we do not intend to make any further breaking changes before v2.0.0, but we may do so in another beta if any issues arise before then.

Highlighted changes

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

Add pretty-printed Debug implementation to BSON types (RUST-282)

BSON related types now support being pretty-printed via the {:#?} format specifier.

e.g.

let doc = doc! {
    "oid": ObjectId::new(),
    "arr": Bson::Array(vec! [
        Bson::Null,
        Bson::Timestamp(Timestamp { time: 1, increment: 1 }),
    ]),
    "doc": doc! { "a": 1, "b": "data"},
};

println!("{:#?}", doc);

Prints the following:

Document({
    "oid": ObjectId(
        "60d60c360026a43f00e47007",
    ),
    "arr": Array([
        Null,
        Timestamp {
            time: 1,
            increment: 1,
        },
    ]),
    "doc": Document({
        "a": Int32(
            1,
        ),
        "b": String(
            "data",
        ),
    }),
})

Implement From<Option<T>> for Bson where T: Into<Bson> (RUST-806)

A blanket From<Option<T>> implementation was added for T that implement Into<Bson>. If the value is Some(T), the T is converted into Bson using T's Into implementation, and if it's None, it will be converted into Bson::Null.

A nice benefit of this is that Option<T> can now be used in the bson! and doc! macros directly:

let some: Option<i32> = Some(5);
let none: Option<i32> = None;
let doc = doc! {
    "some": some,
    "none": none,
};
println!("{}", doc);

Prints:

{ "some": 5, "none": null }

Full Release Notes

New Features

• RUST-806 Implement From<Option<T>> for Bson where T: Into<Bson>
• RUST-841 Mark ObjectId::bytes as const
• RUST-868 Add serialize_object_id_as_hex_string serde helper

Bugfixes

• RUST-755 Use zeroed rather than uninitialized memory for decimal128 deserialization (thanks @5225225 for reporting!)

Improvements

• RUST-282 Add pretty-printed Debug implementation to BSON types
• RUST-672 Introduce new BinarySubtype case for user-defined values
• RUST-838 Improve bson::DateTime::now() performance (thanks @pymongo!)
• RUST-846 Unify Display and Debug implementations for Bson
• RUST-861 Support deserializing ObjectId from non self-describing formats (thanks for reporting @univerz!)
• RUST-876 Quote keys in Document's Display implementation

Task

• RUST-505 Add unit test for Document::extend

v2.0.0-beta.1

Description

The MongoDB Rust driver team is pleased to announce the v2.0.0-beta.1 release of the bson crate. This is the second beta release in preparation for the 2.0.0 stable release, and it contains a few breaking changes, API improvements, and bug fixes that were not included in the first beta. This release will be included in v2.0.0-beta.1 of the driver. As with the previous release, we do not intend to make any further breaking changes before v2.0.0, but we may do so in another beta if any issues arise before then.

Highlighted 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.

bson::DateTime truncates to millisecond precision (RUST-815)

In the previous beta, we included a change that made it an error to attempt to serialize a chrono::DateTime or bson::DateTime that had nonzero microseconds or nanoseconds, since BSON itself only supports millisecond precision. In practice, this ended up being difficult to deal with and broke users' existing code. To remedy this, serializing a chrono::DateTime via the chrono_datetime_as_bson_datetime serde helper automatically truncates the serialized date to millisecond precision rather than returning an error. Similarly, when converting to a bson::DateTime from a chrono::DateTime, the microseconds and nanoseconds are discarded.

Thanks to @vkill for contributing this change!

bson::DateTime ergonomic improvements (RUST-811)

In the first beta, some changes were made to reduce the public dependency on the unstable chrono crate in the public API. This had the unintended effect of making converting between bson::DateTime and chrono::DateTime cumbersome and difficult to discover. To improve on that situation, the bson::DateTime::from_chrono and bson::DateTime::to_chrono methods were introduced to make conversion easier and more explicit.

Given the now expanded presence of chrono, a pre 1.0 crate, in the public API from these changes, these new methods and the existing From implementations were moved to behind the "chrono-0_4" feature flag. This will enable us to continue to add support for new major versions of chrono without having to worry about polluting the public API surface or having to break it altogether. Once chrono reaches 1.0, such support will be included by default without the need for a feature flag. Note that the serde helpers that involve chrono had their version numbers dropped from their names as part of this.

To enable the bson::DateTime type to be more useful on its own, the following methods were also introduced:

• DateTime::now
• DateTime::from_millis
• DateTime::from_system_time
• DateTime::to_system_time

Better handling of datetimes that are very far from the Unix epoch (RUST-799)

In BSON, any datetime within the range of a signed 64-bit integer of milliseconds from the Unix epoch is supported. This is not the case for chrono::DateTime, however, which led to deserialization errors or panics when dates outside of the chrono::DateTime's range were encountered. This has been fixed, and now bson::DateTime can represent any datetime that can be represented in BSON.

Note that bson::DateTime::to_chrono will convert the date to chrono::MAX_DATETIME or chrono::MIN_DATETIME if attempting to convert directly would result in an error.

Properly produce and ingest RFC 3339 (ISO 8601) datetimes in serde helpers (RUST-825)

The iso_string_as_bson_datetime and bson_datetime_as_iso_string serde helpers were not producing or only accepting valid ISO 8601 strings. This has been fixed, and the helpers have been renamed to rfc3339_string_as_bson_datetime and bson_datetime_as_rfc3339_string to more accurately reflect the standard they conform to.

uuid serde helpers were moved behind the "uuid-0_8" feature flag

For consistency with the chrono changes, the uuid serde helpers were moved behind the "uuid-0_8" feature flag. This also will help prevent the public API from being filled with support for outdated versions of the uuid crate as new versions are released. Once uuid reaches 1.0, such support will be included by default without the need for a feature flag. Note that the serde helpers that involve uuid had the version numbers dropped from their names as part of this.

Introduce serde helpers for legacy UUID formats (RUST-687)

The Python, Java, and C# drivers all used to serialize UUIDs with different legacy formats, none of which were supported by the existing UUID serde helper. To add support for serializing and deserializing these UUIDs, new serde helpers were introduced for each of the legacy formats. These helpers are also gated behind the "uuid-0_8" feature flag.

Thanks to @kenkoooo for contributing this change!

Full Release Notes

New Features

• RUST-687 Introduce serde helpers for legacy UUID formats (thanks @kenkoooo!)

Bugfixes

• RUST-799 Fix errors and panics caused by datetimes with large distance to epoch
• RUST-825 Update serde helpers to properly conform with RFC 3339 (ISO 8601) (breaking)

Improvements

• RUST-811 bson::DateTime ergonomic improvements (breaking)
• RUST-815 Truncate chrono::DateTime to millisecond precision when converting to bson::DateTime (breaking) (thanks @vkill!)
• RUST-826 Take ownership of self in ObjectId::to_hex (breaking)

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)

v1.2.2

Release Notes

The MongoDB Rust Driver team is pleased to announce the v1.2.2 release of the BSON library.

This release updates the base64 dependency to 0.13.0 (RUST-686). Thanks to @bugadani for contributing this fix!

v1.2.1

Release Notes

The MongoDB Rust Driver team is pleased to announce the v1.2.1 release of the BSON library.

This release contains a fix for a crash that could occur in Document::from_reader when passed certain types of malformed input. Thank you to @5225225 for reporting the issue and @gperinazzo for fixing it! (RUST-713)

v1.2.0

Description

The MongoDB Rust Driver team is pleased to announce the v1.2.0 release of the BSON library.

Release Notes

Serde Integration Improvements

This release contains several improvements to the library's integration with Serde.

• RUST-506 introduces serde_helpers.rs which contains severals functions and modules to assist in customizing serialization and deserialization of user data types. These functions and modules are compatible with the Serde serialize_with and Serde with field attributes, respectively.
• RUST-507 implements automatic deserialization of BSON number types into unsigned integer types.
• RUST-602 implements automatic deserialization of the ObjectId type from a hexadecimal string.

Other New Features

• RUST-648 Reintroduce Document decoding with lossy UTF-8 encoding
• RUST-589 Implement FromStr for ObjectId
• RUST-364 Cache unique process value for oids
• RUST-554 Support parsing $uuid as extended JSON representation for subtype 4 binary