bson

Overview ¶

Package bson decodes a BSON document (the binary serialization MongoDB stores and that `mongodump` writes to `.bson` files) into a structured tree. It is the document-format complement to mongodb_decode (which dissects the MongoDB *wire protocol* and only shallowly extracts a command name + a few argument fields): this fully, recursively decodes a standalone BSON document — every element type, nested documents and arrays, ObjectId, dates, binary subtypes, regex, timestamps — the way cbor_decode / msgpack_decode handle their formats. An operator pastes the hex of a `.bson` record (mongodump loot, a stored document, a captured payload) and gets the full structure without a MongoDB driver. Pure offline transform; no network or device.

Wrap-vs-native judgement ¶

Native. BSON is a fully public, little-endian, length-prefixed format (bsonspec.org v1.1): a document is an int32 byte-length, a sequence of typed elements (type byte + NUL-terminated name + type-specific value), and a 0x00 terminator. It is a recursive-descent walk over a byte cursor; there is nothing to wrap, and adding go.mongodb.org/mongo-driver/bson as a runtime dependency to decode untrusted bytes is unwarranted. Consistent with internal/cbordecode, internal/msgpack, and internal/protobufdecode owning their parse in-tree.

Verifiable / no confidently-wrong output ¶

Strongest verification class — every element type is gated byte-for-byte against vectors produced by the reference PyMongo `bson` library (double, string, embedded doc, array, binary + subtype, ObjectId, bool, UTC datetime, null, regex, int32, timestamp, int64, decimal128, min/max key, and a nested doc+array). A truncated/malformed document is rejected with an error (never a partial/guessed decode), nesting is depth-capped, and length fields are bounds-checked against the buffer.

Covered / deferred ¶

Covered: all current BSON element types, including Decimal128 (0x13) decoded from its IEEE 754-2008 Binary-Integer-Decimal form to sign + 113-bit coefficient + biased exponent and an exact plain (non-scientific) decimal string, with NaN / ±Infinity surfaced as such (the raw 16 bytes are also kept for traceability). The deprecated DBPointer (0x0C) and Symbol (0x0E) and JavaScript-code-with-scope (0x0F) are decoded structurally.