Skip to content

feat(firestore): add BSONTimestamp support - #18390

Merged
ohmayr merged 1 commit into
mainfrom
bson-pr1e-timestamp
Sep 18, 2026
Merged

ohmayr merged 1 commit into
mainfrom
bson-pr1e-timestamp

Conversation

@ohmayr

@ohmayr ohmayr commented Sep 16, 2026

Copy link
Copy Markdown
Contributor

This PR adds support for BSONTimestamp in the Firestore Python SDK according to the official Firestore BSON specification.

BSONTimestamp represents an internal BSON operation log timestamp containing a 32-bit unsigned seconds count and a 32-bit unsigned increment counter.

BSONTimestamp Container Class: Implements BSONTimestamp(_BSONType) in google.cloud.firestore_v1.bson, wrapping seconds and increment values.

  • Spec-Compliant Unsigned Conversion: Automatically converts negative signed int32 inputs ($-2^{31} \le \text{val} &lt; 0$) into unsigned long representation using val % (1 << 32) (e.g. -14,294,967,295).
  • Wire Serialization (_to_map_value): Serializes to {"__request_timestamp__": {"seconds": self._seconds, "increment": self._increment}}.
  • Defensive Input Validation: Rejects booleans and non-integer inputs with TypeError, and rejects values outside the $[-2^{31}, 2^{32}-1]$ bounds with ValueError.
  • SDK Exports & Post-Processing: Exported BSONTimestamp in google.cloud.firestore and google.cloud.firestore_v1, and updated .librarian/generator-input/client-post-processing/firestore-integration.yaml.

Fixes b/562193816 🦕

@ohmayr
ohmayr added this pull request to stack #18386 September 16, 2026 01:46

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces the BSONTimestamp class to represent BSON Timestamp containers for Firestore operation log entries, complete with validation, signed-to-unsigned conversion, and comprehensive unit and system tests. The review feedback points out an inconsistency in the validation error message, which states the value must be between 0 and 4294967295, even though negative signed 32-bit integers are accepted and converted. A code suggestion is provided to simplify the validation logic and make the error message accurate.

Comment thread packages/google-cloud-firestore/google/cloud/firestore_v1/bson.py Outdated
@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch from d023275 to 07ee207 Compare September 16, 2026 02:01
@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch 2 times, most recently from 3433917 to e2483dc Compare September 16, 2026 02:10
@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch from e2483dc to c216bc2 Compare September 16, 2026 02:25
@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch from c216bc2 to 93363ca Compare September 16, 2026 02:33
@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch 2 times, most recently from d9a766f to a7196a4 Compare September 16, 2026 02:44
@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch from a7196a4 to e7103a0 Compare September 16, 2026 07:43
@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch 2 times, most recently from f15adf5 to 518b452 Compare September 16, 2026 08:15
@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch 3 times, most recently from 6cdffad to 2c2f615 Compare September 16, 2026 08:35
@ohmayr
ohmayr marked this pull request as ready for review September 16, 2026 08:37
@ohmayr
ohmayr requested review from a team as code owners September 16, 2026 08:37
@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch from 2c2f615 to c8959bf Compare September 16, 2026 20:02
@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch from c8959bf to 770f47d Compare September 16, 2026 20:43
@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch from 770f47d to e612561 Compare September 16, 2026 20:57
@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch from e612561 to f60d61d Compare September 16, 2026 21:58
@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch from f60d61d to 959e215 Compare September 16, 2026 22:11

Args:
seconds (int): Seconds count.
increment (int): Increment/ordinal.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: it's not clear to me what increment means here. But I tried looking at other docs, and it doesn't seem well defined there either. Maybe this is more clear to the intended user

@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch from 959e215 to cb4fa7a Compare September 18, 2026 20:06
Base automatically changed from bson-pr1d-binary to main September 18, 2026 22:11
@ohmayr
ohmayr force-pushed the bson-pr1e-timestamp branch from cb4fa7a to 0164226 Compare September 18, 2026 22:11
@ohmayr
ohmayr merged commit a1b2d63 into main Sep 18, 2026
48 checks passed
@ohmayr
ohmayr deleted the bson-pr1e-timestamp branch September 18, 2026 22:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants