src/uuid/uuid.go

// Copyright 2026 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Package uuid provides support for generating and manipulating UUIDs.
//
// See [RFC 9562] for details.
//
// Random components of new UUIDs are generated with a
// cryptographically secure random number generator.
//
// UUIDs may be generated using various algorithms.
// The [New] function returns a new UUID generated using
// an algorithm suitable for most purposes.
//
// [RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562.html
package uuid

import (
	"bytes"
	"cmp"
	"crypto/rand"
	"encoding/binary"
	"encoding/hex"
	"errors"
	"sync"
	"time"
)

// A UUID is a Universally Unique Identifier as specified in RFC 9562.
//
// UUIDs are comparable, such as with the == operator.
type UUID [16]byte

// Parse returns the UUID represented by s.
//
// It accepts strings in the following forms:
//
//	f81d4fae-7dec-11d0-a765-00a0c91e6bf6
//	{f81d4fae-7dec-11d0-a765-00a0c91e6bf6}
//	urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
//	f81d4fae7dec11d0a76500a0c91e6bf6
//
// Alphabetic characters in the hexadecimal digits may be any case.
func Parse(s string) (UUID, error) {
	var u UUID
	err := u.UnmarshalText([]byte(s))
	return u, err
}

// MustParse returns the UUID represented by s.
//
// It panics if s is not a valid string representation of a UUID as defined by [Parse].
func MustParse(s string) UUID {
	u, err := Parse(s)
	if err != nil {
		panic(err)
	}
	return u
}

// New returns a new UUID.
//
// Programs which do not have a need for a specific UUID generation algorithm should use New.
// At this time, New is equivalent to [NewV4].
func New() UUID {
	return NewV4()
}

// Nil returns the Nil UUID 00000000-0000-0000-0000-000000000000.
//
// The Nil UUID is defined in [Section 5.9 of RFC 9562].
// Note that this is not the same as the Go value nil.
//
// [Section 5.9 of RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562#section-5.9
func Nil() UUID {
	return UUID{}
}

// Max returns the Max UUID ffffffff-ffff-ffff-ffff-ffffffffffff.
//
// The Max UUID is defined in [Section 5.10 of RFC 9562].
//
// [Section 5.10 of RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562#section-5.10
func Max() UUID {
	return UUID{
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
		0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
	}
}

// String returns the string representation of u.
//
// It uses the lowercase hex-and-dash representation defined in RFC 9562.
func (u UUID) String() string {
	b, _ := u.MarshalText()
	return string(b)
}

// MarshalText implements the [encoding.TextMarshaler] interface.
// The encoding is the same as returned by [UUID.String]
func (u UUID) MarshalText() ([]byte, error) {
	return u.AppendText(make([]byte, 0, 36))
}

// AppendText implements the [encoding.TextAppender] interface.
// The encoding is the same as returned by [UUID.String]
func (u UUID) AppendText(b []byte) ([]byte, error) {
	off := len(b)
	b = append(b, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"...)
	dst := b[off:]
	hex.Encode(dst[0:8], u[0:4])
	hex.Encode(dst[9:13], u[4:6])
	hex.Encode(dst[14:18], u[6:8])
	hex.Encode(dst[19:23], u[8:10])
	hex.Encode(dst[24:36], u[10:16])
	return b, nil
}

var errInvalid = errors.New("invalid uuid")

// UnmarshalText implements the [encoding.TextUnmarshaler] interface.
// The UUID is expected in a form accepted by [Parse].
func (u *UUID) UnmarshalText(b []byte) error {
	var dst UUID
	switch len(b) {
	case len("urn:uuid:") + 36:
		// urn:uuid:00000000-0000-0000-0000-000000000000
		b = bytes.TrimPrefix(b, []byte("urn:uuid:"))
	case 2 + 36:
		// {00000000-0000-0000-0000-000000000000}
		b = bytes.TrimPrefix(b, []byte("{"))
		b = bytes.TrimSuffix(b, []byte("}"))
	case 32:
		// 00000000000000000000000000000000
		if _, err := hex.Decode(dst[:], b); err != nil {
			return errInvalid
		}
		*u = dst
		return nil
	}
	// 00000000-0000-0000-0000-000000000000
	if len(b) != 36 {
		return errInvalid
	}
	if b[8] != '-' || b[13] != '-' || b[18] != '-' || b[23] != '-' {
		return errInvalid
	}
	if _, err := hex.Decode(dst[0:4], b[0:8]); err != nil {
		return errInvalid
	}
	if _, err := hex.Decode(dst[4:6], b[9:13]); err != nil {
		return errInvalid
	}
	if _, err := hex.Decode(dst[6:8], b[14:18]); err != nil {
		return errInvalid
	}
	if _, err := hex.Decode(dst[8:10], b[19:23]); err != nil {
		return errInvalid
	}
	if _, err := hex.Decode(dst[10:16], b[24:36]); err != nil {
		return errInvalid
	}
	*u = dst
	return nil
}

// Compare compares the UUID u with v.
// If u is before v, it returns -1.
// If u is after v, it returns +1.
// If they are the same, it returns 0.
//
// Compare uses the big-endian byte order defined in
// [Section 6.11 of RFC 9562] for sorting.
//
// [Section 6.11 of RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562#section-6.11
func (u UUID) Compare(v UUID) int {
	for i := range u {
		if c := cmp.Compare(u[i], v[i]); c != 0 {
			return c
		}
	}
	return 0
}

// NewV4 returns a new version 4 UUID.
//
// Version 4 UUIDs contain 122 bits of random data.
func NewV4() UUID {
	var u UUID
	rand.Read(u[:])
	u.setVersion(4)
	u.setVariant(0b10)
	return u
}

var (
	v7mu            sync.Mutex
	v7lastSecs      uint64
	v7lastTimestamp uint64
)

// NewV7 returns a new version 7 UUID.
//
// Version 7 UUIDs contain a timestamp in the most significant 48 bits,
// and at least 62 bits of random data.
//
// NewV7 always returns UUIDs which sort in increasing order,
// except when the system clock moves backwards.
func NewV7() UUID {
	// UUIDv7 is defined in RFC 9562 section 5.7 as:
	//
	//  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
	// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
	// |                           unix_ts_ms                          |
	// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
	// |          unix_ts_ms           |  ver  |       rand_a          |
	// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
	// |var|                        rand_b                             |
	// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
	// |                            rand_b                             |
	// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
	//
	// We store a 12 bit sub-millisecond timestamp fraction in the rand_a section,
	// as optionally permitted by the RFC.
	v7mu.Lock()

	// Generate our 60-bit timestamp: 48 bits of millisecond-resolution,
	// followed by 12 bits of 1/4096-millisecond resolution.
	now := time.Now()
	secs := uint64(now.Unix())
	nanos := uint64(now.Nanosecond())
	msecs := nanos / 1000000
	frac := nanos - (1000000 * msecs)
	timestamp := (1000*secs + msecs) << 12 // ms shifted into position
	timestamp += (frac * 4096) / 1000000   // ns converted to 1/4096-ms units

	if v7lastSecs > secs {
		// Time has gone backwards.
		// This presumably indicates the system clock has changed.
		// Ignore previously-generated UUIDs.
	} else if timestamp <= v7lastTimestamp {
		// This timestamp is the same as a previously-generated UUID.
		// To preserve the property that we generate UUIDs in order,
		// use a timestamp 1/4096 millisecond later than the most recently
		// generated UUID.
		timestamp = v7lastTimestamp + 1
	}

	v7lastSecs = secs
	v7lastTimestamp = timestamp
	v7mu.Unlock()

	// Insert a gap for the 4 bits of the ver field into the timestamp.
	hibits := ((timestamp << 4) & 0xffff_ffff_ffff_0000) | (timestamp & 0x0ffff)

	var u UUID
	binary.BigEndian.PutUint64(u[0:8], hibits)
	rand.Read(u[8:])
	u.setVersion(7)
	u.setVariant(0b10)

	return u
}

func (u *UUID) setVersion(version byte) {
	u[6] = (u[6] & 0b0000_1111) | (version << 4)
}

func (u *UUID) setVariant(variant byte) {
	u[8] = (u[8] & 0b0011_1111) | (variant << 6)
}