fix: Monotonicity in UUIDv7

[it512]

Monotonicity in UUIDv7
#148

[conventional-commit-lint-gcf]

🤖 I detect that the PR title and the commit message differ and there's only one commit. To use the PR title for the commit history, you can use Github's automerge feature with squashing, or use automerge label. Good luck human!

-- conventional-commit-lint bot
https://conventionalcommits.org/

[bormanp]

this message is no longer accurate.

[bormanp]

Should this be >= ?

[it512]

ok

[bormanp]

As I understand it, this is not a limitation of the implementation but rather of the standard.

// Note: Version 7 UUIDs have a 12 bit sequence number limiting the number of 
// unique UUIDs to 4096 in 1 millesecond.

[bormanp]

I don 't think this is quite right. Maybe something along the lines of:

now := time.Now().UnixNano()
milli := now / 1000
seq := (now - milli * 1000) << 2 // use the upper 10 bits

There is nothing in the standard that requires Version 7 UUIDs to be monotonically increasing within a given millisecond but it is acceptable to use sub-millisecond values. It is also legitimate for the first 64 bits of two Version 7 UUIDs to be identical. The randomness in the last 62 bits is what makes them unique.

[bormanp]

I misread part of the standard, it should be monotonic, but the above is still basically correct. What you need to do is have a protected global variable:

now := time.Now().UnixNano() << 2 // time in 1/4 nanoseconds
if now <= lastTime {
    now = lastTime + 1
}
lastTime = now
milli := now / 4000
seq := now - milli * 4000

By using 1/4 nanoseconds we can generate 4 UUIDs within a nanosecond that do not cause us to return a time that is actually in the future by a nanosecond.

[it512]

v7 using millisecond (1/1000) timestamp, we are using microsecond (1/1000000) lower 12 bit set to rand_a
1 millisecond can generate 4096 uuids

now := timeNow().UnixMicro()
 t, s := now/1000, now&4095 // 2^12-1, 12 bits
 uuid[6] = 0x70 | (0x0F & byte(s>>8))
 uuid[7] = byte(s)

[bormanp]

s/expected/unexpected

[it512]

ok

[it512]

Thank you for review, fixed

[bormanp]

This forces this single test to take a full second. A better test might be to force timeNow to return the same time on every call. You don't need to store all the UUIDs, just the last one:

u, _ := NewV7()
lastUUID := u.String()
for i := 0; i < length; i++ {
        u, _ := Newv7()
        nextUUID := u.String()   
        if lastUUID >= nextUUID {
                t.Errorf("monotonicity failed at #%d: %s !< %s", i, lastUUID, nextUUID)
                break
        }
}

You could also run this test again where timeNow returns time incrementing by say 100 nanoseconds per call and if you want to go crazy, where timeNow returns time going backwards.

[bormanp]

so this can still return a UUID that is less than the previous UUID (two calls within the same microsecond).

The only way to guarantee an always increasing UUID is to remember the last time/sequence returned. Perhaps something like:

// lastV7time is the last last time we returned stored as:
//      
//      52 bits of time in milliseconds since epoch
//      12 bits of (fractional nanoseconds) >> 8
var lastV7time int64

const nanoPerMilli = 1000000

// getV7Time returns the time in milliseconds and nanoseconds / 256.
// The returned (milli << 12 + seq) is guarenteed to be greater than
// (milli << 12 + seq) returned by any previous call to getV7Time.
func getV7Time() (milli, seq int64) {
        nano := timeNow().UnixNano()
        milli = nano / nanoPerMilli
        // Sequence number is between 0 and 3906 (nanoPerMilli>>8)
        seq = (nano - milli*nanoPerMilli) >> 8
        now := milli<<12 + seq
        if now <= lastV7time {   
                now = lastV7time + 1
                milli = now >> 12
                seq = now & 0xfff
        }
        lastV7time = now
        return milli, seq
}

[bormanp]

Just a comment issue. Also the commit message did not follow Conventional Commits causing the presubmit tests to fail.

https://github.com/google/uuid/pull/150/checks?check_run_id=20377607744

[bormanp]

The period was lost here. In general, do not reformat comments unless they are incorrect.

[it512]

fixed

[sergeyprokhorenko]

I advise you to take the following implementations as an example:
Rust
PostgreSQL
It is these implementations, created with the participation of the most important RFC contributors (LiosK and Sergey Prokhorenko), that are closest to understanding the RFC.

[bensie]

Thanks for your work on this @it512!