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

106