[DOCS-9384] BSON spec conflicts with documentation over Timestamp structure Created: 28/Nov/16  Updated: 30/Oct/23  Resolved: 01/Oct/19

Status: Closed
Project: Documentation
Component/s: bsonspec, manual, Server
Affects Version/s: None
Fix Version/s: Server_Docs_20231030

Type: Bug Priority: Minor - P4
Reporter: Jeremy Mikola Assignee: Andrew Feierabend (Inactive)
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
related to PHPC-845 Timestamp constructor should take tim... Closed
related to DOCS-9787 Clarify that each component of an Obj... Closed
Participants:
Days since reply: 4 years, 12 weeks, 5 days ago
Epic Link: DOCSP-1769
Story Points: 0.5

 Description   

Timestamp - Special internal type used by MongoDB replication and sharding. First 4 bytes are an increment, second 4 are a timestamp.

Source: http://bsonspec.org/spec.html

Timestamp values are a 64 bit value where:

  • the first 32 bits are a time_t value (seconds since the Unix epoch)
  • the second 32 bits are an incrementing ordinal for operations within a given second.

Source: https://docs.mongodb.com/v3.2/reference/bson-types/#timestamps



 Comments   
Comment by Githook User [ 15/Nov/19 ]

Author:

{'name': 'Andrew Feierabend', 'username': 'andf-mongodb', 'email': 'andrew.feierabend@mongodb.com'}

Message: DOCS-9384 Clarify BSON timestamp endianness
Branch: v3.4
https://github.com/mongodb/docs/commit/521a44dbc9feedf67053f11cb6d5b5900f2ab337

Comment by Githook User [ 15/Nov/19 ]

Author:

{'name': 'Andrew Feierabend', 'username': 'andf-mongodb', 'email': 'andrew.feierabend@mongodb.com'}

Message: DOCS-9384 Clarify BSON timestamp endianness
Branch: v3.6
https://github.com/mongodb/docs/commit/0b141f0b9e5b00e051e43582ef7874b6b8aba517

Comment by Githook User [ 15/Nov/19 ]

Author:

{'name': 'Andrew Feierabend', 'username': 'andf-mongodb', 'email': 'andrew.feierabend@mongodb.com'}

Message: DOCS-9384 Clarify BSON timestamp endianness
Branch: v4.0
https://github.com/mongodb/docs/commit/02946395644760aff596632b28df26362305f57c

Comment by Githook User [ 15/Nov/19 ]

Author:

{'name': 'Andrew Feierabend', 'username': 'andf-mongodb', 'email': 'andrew.feierabend@mongodb.com'}

Message: DOCS-9384 Clarify BSON timestamp endianness
Branch: master
https://github.com/mongodb/docs/commit/522d636e9b3ad84639fe73df36a73dc00cc0156b

Comment by Andrew Feierabend (Inactive) [ 01/Oct/19 ]

Updated language to discuss endianness in context of this field.

Comment by Jeremy Mikola [ 17/Jan/17 ]

Side note: Timestamps are compared as unsigned long long values in the server. When the type is converted to an unsigned long long, the 4-byte time component is always shifted to the most significant bits. This ensures that the time is compared before the incrementing ordinal on all platforms, regardless of endianness.

Comment by Jeremy Mikola [ 17/Jan/17 ]

After sorting through the server source a bit more (with some help from david.storch), david.golden and I concluded that BSON spec is correct and the MongoDB manual is need of a fix.

BSON Types: Timestamps says:

Timestamp values are a 64 bit value where:

  • the first 32 bits are a time_t value (seconds since the Unix epoch)
  • the second 32 bits are an incrementing ordinal for operations within a given second.

This should say:

Timestamp values are a 64 bit value where:

  • the most significant 32 bits are a time_t value (seconds since the Unix epoch)
  • the least significant 32 bits are an incrementing ordinal for operations within a given second.

That page does not reiterate the fact that BSON is little endian; however, this effectively means that the first four bytes contain the ordinal, followed by the time component. I believe BSON's little endianness is only discussed on the spec website, where we say "Each type must be serialized in little-endian format." If we ever decide to reiterate BSON's little endianness in our manual, it may be helpful to add a note clarifying how most and least significant in this instance relates to byte order.

Comment by David Golden [ 17/Jan/17 ]

jmikola, I see. This ticket is reporting that the spec is wrong. That wasn't clear from the subject.

Looking at some implementations as well as the BSON corpus, I'm surprised this wasn't caught earlier. We'll also need SPEC and DRIVER tickets for this if you haven't filed them.

In any case, I've looked at the server source and agree that the first 4 bytes are the timestamp and the second 4 are the increment.

allison.moore, the spec needs to be changed to match the documentation.

Comment by Jeremy Mikola [ 17/Jan/17 ]

david.golden: In this case, BSON spec is actually incorrect. The first four bytes in a BSON timestamp are the time_t value, followed by an incrementing ordinal. This is akin to an ObjectID being prefixed with a timestamp for sorting purposes.

Comment by Allison Reinheimer Moore [ 17/Jan/17 ]

david.golden Excellent. Thanks!

Generated at Thu Feb 08 07:58:15 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.