git.sr.ht/~pingoo/stdx@v0.0.0-20240218134121-094174641f6e/uuid/v7.go (about)

     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 {
    24  	uuid := Must(newRandom())
    25  	makeV7(uuid[:])
    26  	return uuid
    27  }
    28  
    29  // NewV7FromReader returns a Version 7 UUID based on the current time(Unix Epoch).
    30  // it use NewRandomFromReader fill random bits.
    31  // On error, NewV7FromReader returns Nil and an error.
    32  func NewV7FromReader(r io.Reader) (UUID, error) {
    33  	uuid, err := NewRandomFromReader(r)
    34  	if err != nil {
    35  		return uuid, err
    36  	}
    37  
    38  	makeV7(uuid[:])
    39  	return uuid, nil
    40  }
    41  
    42  // makeV7 fill 48 bits time (uuid[0] - uuid[5]), set version b0111 (uuid[6])
    43  // uuid[8] already has the right version number (Variant is 10)
    44  // see function NewV7 and NewV7FromReader
    45  func makeV7(uuid []byte) {
    46  	/*
    47  		 0                   1                   2                   3
    48  		 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
    49  		+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    50  		|                           unix_ts_ms                          |
    51  		+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    52  		|          unix_ts_ms           |  ver  |  rand_a (12 bit seq)  |
    53  		+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    54  		|var|                        rand_b                             |
    55  		+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    56  		|                            rand_b                             |
    57  		+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    58  	*/
    59  	_ = uuid[15] // bounds check
    60  
    61  	t, s := getV7Time()
    62  
    63  	uuid[0] = byte(t >> 40)
    64  	uuid[1] = byte(t >> 32)
    65  	uuid[2] = byte(t >> 24)
    66  	uuid[3] = byte(t >> 16)
    67  	uuid[4] = byte(t >> 8)
    68  	uuid[5] = byte(t)
    69  
    70  	uuid[6] = 0x70 | (0x0F & byte(s>>8))
    71  	uuid[7] = byte(s)
    72  }
    73  
    74  // lastV7time is the last time we returned stored as:
    75  //
    76  //	52 bits of time in milliseconds since epoch
    77  //	12 bits of (fractional nanoseconds) >> 8
    78  var lastV7time int64
    79  
    80  const nanoPerMilli = 1000000
    81  
    82  // getV7Time returns the time in milliseconds and nanoseconds / 256.
    83  // The returned (milli << 12 + seq) is guarenteed to be greater than
    84  // (milli << 12 + seq) returned by any previous call to getV7Time.
    85  func getV7Time() (milli, seq int64) {
    86  	timeMu.Lock()
    87  	defer timeMu.Unlock()
    88  
    89  	nano := timeNow().UnixNano()
    90  	milli = nano / nanoPerMilli
    91  	// Sequence number is between 0 and 3906 (nanoPerMilli>>8)
    92  	seq = (nano - milli*nanoPerMilli) >> 8
    93  	now := milli<<12 + seq
    94  	if now <= lastV7time {
    95  		now = lastV7time + 1
    96  		milli = now >> 12
    97  		seq = now & 0xfff
    98  	}
    99  	lastV7time = now
   100  	return milli, seq
   101  }