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

v1.1.0

Description

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

Release Notes

In addition to the changes listed for the v1.1.0-beta, the following change was made since v1.0.0:

New Features

• RUST-503 Support serializing directly to and deserializing directly from Document

v1.1.0-beta

Description

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

Release Notes

Bug fixes

• RUST-511 Fix incorrect Deserialize requirement on generic type in from_bson
• #197 Bump linked-hash-map due to fix unsoundness

New Features

• RUST-475 Add getter for timestamp from ObjectId

Improvements

• RUST-510 Remove unneeded dependencies

v1.0.0

Description

The MongoDB Rust Driver team is pleased to announce the first stable release of the BSON library, v1.0.0. Per semver requirements, no breaking changes will be made in future 1.x releases of this library.

Major Changes

See the release notes for v0.15.0 for details on the recent breaking changes in the BSON library.