Draft 03 (#34)

* Draft 03

Author: oittaa

README.md

@@ -34,62 +34,59 @@ assert my_uuid < uuid7()
 ```
         0                   1                   2                   3
         0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-       |                           time_high                           |
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-       |           time_mid            |      time_low_and_version     |
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-       |clk_seq_hi_res |  clk_seq_low  |         node (0-1)            |
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-       |                         node (2-5)                            |
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        |                           time_high                           |
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        |           time_mid            |      time_low_and_version     |
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        |clk_seq_hi_res |  clk_seq_low  |         node (0-1)            |
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        |                         node (2-5)                            |
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 ```
 
 ## UUIDv7 Field and Bit Layout
 
-### [Draft 02][draft 02]
+### [Draft 03][draft 03]
 
 ```
         0                   1                   2                   3
         0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-       |                            unixts                             |
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-       |unixts |       subsec_a        |  ver  |       subsec_b        |
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-       |var|                   subsec_seq_node                         |
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-       |                       subsec_seq_node                         |
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        |                           unix_ts_ms                          |
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        |          unix_ts_ms           |  ver  |       rand_a          |
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        |var|                        rand_b                             |
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        |                            rand_b                             |
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 ```
 
 ### This implementation
 
 ```
         0                   1                   2                   3
         0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-       |                            unixts                             |
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-       |unixts |       subsec_a        |  ver  |       subsec_b        |
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-       |var| subsec_c  |             rand                              |
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-       |                             rand                              |
-       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        |                           unix_ts_ms                          |
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        |          unix_ts_ms           |  ver  |      subsec_a         |
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        |var|   subsec_b    |         rand                              |
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+        |                             rand                              |
+        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 ```
 
-- `unixts`: 36 bit big-endian unsigned Unix Timestamp value
-- `subsec_a`: 12 bits allocated to sub-second precision values
+- `unix_ts_ms`: 48 bit big-endian unsigned number of Unix epoch timestamp with millisecond level of precision
 - `ver`: The 4 bit UUIDv7 version (0111)
-- `subsec_b`: 12 bits allocated to sub-second precision values
+- `subsec_a`: 12 bits allocated to sub-second precision values
 - `var`: 2 bit UUID variant (10)
-- `subsec_c`: 6 bits allocated to sub-second precision values
-- `rand`: The remaining 56 bits are filled with pseudo-random data
-
- 30 bits dedicated to sub-second precision provide nanosecond resolution. The `unixts` and `subsec` fields guarantee the order of UUIDs generated within the same nanosecond by monotonically incrementing the timer.
+- `subsec_b`: 8 bits allocated to sub-second precision values
+- `rand`: The remaining 54 bits are filled with pseudo-random data
 
-This implementation does not include a clock sequence counter as defined in the draft RFC.
+ 20 extra bits dedicated to sub-second precision provide nanosecond resolution. The `unix_ts` and `subsec` fields guarantee the order of UUIDs generated within the same nanosecond by monotonically incrementing the timer.
 
 ## Performance
 
@@ -126,6 +123,6 @@ Mean +- std dev: 7.51 us +- 1.42 us
 ```
 
 [ietf draft]: https://github.com/uuid6/uuid6-ietf-draft
-[draft 02]: https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-02#section-4.4
+[draft 03]: https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-03#section-5.2
 [cloud shell]: https://cloud.google.com/shell/docs
 [bench]: https://github.com/oittaa/uuid6-python/blob/main/bench.sh

src/uuid6/__init__.py

@@ -51,11 +51,7 @@ def __init__(
 
     @property
     def subsec(self) -> int:
-        return (
-            (self.time_mid & 0x0FFF) << 18
-            | (self.time_hi_version & 0x0FFF) << 6
-            | self.clock_seq_hi_variant & 0x3F
-        )
+        return ((self.int >> 64) & 0x0FFF) << 8 | ((self.int >> 54) & 0xFF)
 
     @property
     def time(self) -> int:
@@ -66,20 +62,16 @@ def time(self) -> int:
                 | (self.time_hi_version & 0x0FFF)
             )
         if self.version == 7:
-            return self.unixts * 10**9 + _subsec_decode(self.subsec)
+            return (self.int >> 80) * 10**6 + _subsec_decode(self.subsec)
         return super().time
 
-    @property
-    def unixts(self) -> int:
-        return self.time_low << 4 | self.time_mid >> 12
-
 
 def _subsec_decode(value: int) -> int:
-    return -(-value * 10**9 // 2**30)
+    return -(-value * 10**6 // 2**20)
 
 
 def _subsec_encode(value: int) -> int:
-    return value * 2**30 // 10**9
+    return value * 2**20 // 10**6
 
 
 _last_v6_timestamp = None
@@ -127,15 +119,13 @@ def uuid7() -> UUID:
     if _last_v7_timestamp is not None and nanoseconds <= _last_v7_timestamp:
         nanoseconds = _last_v7_timestamp + 1
     _last_v7_timestamp = nanoseconds
-    timestamp_s, timestamp_ns = divmod(nanoseconds, 10**9)
+    timestamp_ms, timestamp_ns = divmod(nanoseconds, 10**6)
     subsec = _subsec_encode(timestamp_ns)
-    subsec_a = subsec >> 18
-    subsec_b = (subsec >> 6) & 0x0FFF
-    subsec_c = subsec & 0x3F
-    rand = secrets.randbits(56)
-    uuid_int = (timestamp_s & 0x0FFFFFFFFF) << 92
-    uuid_int |= subsec_a << 80
-    uuid_int |= subsec_b << 64
-    uuid_int |= subsec_c << 56
+    subsec_a = subsec >> 8
+    subsec_b = subsec & 0xFF
+    rand = secrets.randbits(54)
+    uuid_int = (timestamp_ms & 0xFFFFFFFFFFFF) << 80
+    uuid_int |= subsec_a << 64
+    uuid_int |= subsec_b << 54
     uuid_int |= rand
     return UUID(int=uuid_int, version=7)

test/test_uuid6.py

@@ -1,5 +1,4 @@
 import unittest
-from datetime import datetime
 from time import time_ns
 from unittest.mock import patch
 from uuid import uuid1
@@ -91,17 +90,12 @@ def test_uuid6_far_in_future(self):
     def test_uuid7_far_in_future(self):
         with patch("time.time_ns", return_value=1):
             uuid_prev = uuid7()
-        for i in range(1, 2170):
+        for i in range(1, 8000):
             with patch("time.time_ns", return_value=i * YEAR_IN_NS):
                 uuid_cur = uuid7()
                 self.assertLess(uuid_prev, uuid_cur)
                 uuid_prev = uuid_cur
 
-        # Overflow after 2 ** 36 seconds
-        with patch("time.time_ns", return_value=2178 * YEAR_IN_NS):
-            uuid_2178_from_epoch = uuid7()
-        self.assertLess(uuid_2178_from_epoch, uuid_prev)
-
     def test_time(self):
         uuid_1 = uuid1()
         uuid_6 = uuid6()
@@ -110,23 +104,27 @@ def test_time(self):
         uuid_7 = uuid7()
         self.assertAlmostEqual(uuid_7.time / 10**9, cur_time / 10**9, 3)
 
-    def test_time_zero(self):
+    def test_zero_time(self):
         uuid_6 = UUID(hex="00000000-0000-6000-8000-000000000000")
         self.assertEqual(uuid_6.time, 0)
         uuid_7 = UUID(hex="00000000-0000-7000-8000-000000000000")
         self.assertEqual(uuid_7.time, 0)
 
-    def test_time_max(self):
+    def test_max_time(self):
         uuid_6 = UUID(hex="ffffffff-ffff-6fff-bfff-ffffffffffff")
         self.assertEqual(uuid_6.time, 1152921504606846975)
         uuid_7 = UUID(hex="ffffffff-ffff-7fff-bfff-ffffffffffff")
-        self.assertEqual(uuid_7.time, 68719476736000000000)
-        dt = datetime.utcfromtimestamp(uuid_7.time / 10**9)
-        self.assertEqual(dt, datetime(4147, 8, 20, 7, 32, 16))
+        self.assertEqual(uuid_7.time, 281474976710656000000)
+
+    def test_uuid6_test_vector(self):
+        uuid_6 = UUID(hex="1EC9414C-232A-6B00-B3C8-9E6BDECED846")
+        self.assertEqual(uuid_6.time, 138648505420000000)
+        uuid_1 = UUID(hex="C232AB00-9414-11EC-B3C8-9E6BDECED846")
+        self.assertEqual(uuid_6.time, uuid_1.time)
 
-    def test_uuid7_from_hex(self):
-        uuid_7 = UUID(hex="061d0edc-bea0-75cc-9892-f6295fd7d295")
-        self.assertEqual(uuid_7.time, 1641082315914150976)
+    def test_uuid7_test_vector(self):
+        uuid_7 = UUID(hex="017F21CF-D130-7CC3-98C4-DC0C0C07398F")
+        self.assertEqual(uuid_7.time // 10**6, 1645539742000)
 
     def test_multiple_arguments(self):
         with self.assertRaises(TypeError):