1 // Copyright 2023 Google Inc. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
4 5 package uuid
6 7 import (
8 "io"
9 )
10 11 // UUID version 7 features a time-ordered value field derived from the widely
12 // implemented and well known Unix Epoch timestamp source,
13 // the number of milliseconds seconds since midnight 1 Jan 1970 UTC, leap seconds excluded.
14 // As well as improved entropy characteristics over versions 1 or 6.
15 //
16 // see https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-03#name-uuid-version-7
17 //
18 // Implementations SHOULD utilize UUID version 7 over UUID version 1 and 6 if possible.
19 //
20 // NewV7 returns a Version 7 UUID based on the current time(Unix Epoch).
21 // Uses the randomness pool if it was enabled with EnableRandPool.
22 // On error, NewV7 returns Nil and an error
23 func NewV7() (UUID, error) {
24 uuid, err := NewRandom()
25 if err != nil {
26 return uuid, err
27 }
28 makeV7(uuid[:])
29 return uuid, nil
30 }
31 32 // NewV7FromReader returns a Version 7 UUID based on the current time(Unix Epoch).
33 // it use NewRandomFromReader fill random bits.
34 // On error, NewV7FromReader returns Nil and an error.
35 func NewV7FromReader(r io.Reader) (UUID, error) {
36 uuid, err := NewRandomFromReader(r)
37 if err != nil {
38 return uuid, err
39 }
40 41 makeV7(uuid[:])
42 return uuid, nil
43 }
44 45 // makeV7 fill 48 bits time (uuid[0] - uuid[5]), set version b0111 (uuid[6])
46 // uuid[8] already has the right version number (Variant is 10)
47 // see function NewV7 and NewV7FromReader
48 func makeV7(uuid []byte) {
49 /*
50 0 1 2 3
51 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
52 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
53 | unix_ts_ms |
54 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
55 | unix_ts_ms | ver | rand_a (12 bit seq) |
56 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
57 |var| rand_b |
58 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
59 | rand_b |
60 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
61 */
62 _ = uuid[15] // bounds check
63 64 t, s := getV7Time()
65 66 uuid[0] = byte(t >> 40)
67 uuid[1] = byte(t >> 32)
68 uuid[2] = byte(t >> 24)
69 uuid[3] = byte(t >> 16)
70 uuid[4] = byte(t >> 8)
71 uuid[5] = byte(t)
72 73 uuid[6] = 0x70 | (0x0F & byte(s>>8))
74 uuid[7] = byte(s)
75 }
76 77 // lastV7time is the last time we returned stored as:
78 //
79 // 52 bits of time in milliseconds since epoch
80 // 12 bits of (fractional nanoseconds) >> 8
81 var lastV7time int64
82 83 const nanoPerMilli = 1000000
84 85 // getV7Time returns the time in milliseconds and nanoseconds / 256.
86 // The returned (milli << 12 + seq) is guarenteed to be greater than
87 // (milli << 12 + seq) returned by any previous call to getV7Time.
88 func getV7Time() (milli, seq int64) {
89 timeMu.Lock()
90 defer timeMu.Unlock()
91 92 nano := timeNow().UnixNano()
93 milli = nano / nanoPerMilli
94 // Sequence number is between 0 and 3906 (nanoPerMilli>>8)
95 seq = (nano - milli*nanoPerMilli) >> 8
96 now := milli<<12 + seq
97 if now <= lastV7time {
98 now = lastV7time + 1
99 milli = now >> 12
100 seq = now & 0xfff
101 }
102 lastV7time = now
103 return milli, seq
104 }
105