Merge branch 'google:master' into master

tkarrass · web-flow · commit e0fadb53ad7b · 2024-09-11T10:57:10.000+02:00
diff --git a/.github/workflows/apidiff.yaml b/.github/workflows/apidiff.yaml
@@ -4,6 +4,8 @@ on:
   pull_request:
     branches:
       - master
+permissions:
+  contents: read
 jobs:
   compat:
     runs-on: ubuntu-latest
diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
@@ -4,6 +4,8 @@ on:
   pull_request:
     branches:
       - master
+permissions:
+  contents: read
 jobs:
   unit-tests:
     strategy:
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,25 @@
 # Changelog
 
+## [1.6.0](https://github.com/google/uuid/compare/v1.5.0...v1.6.0) (2024-01-16)
+
+
+### Features
+
+* add Max UUID constant ([#149](https://github.com/google/uuid/issues/149)) ([c58770e](https://github.com/google/uuid/commit/c58770eb495f55fe2ced6284f93c5158a62e53e3))
+
+
+### Bug Fixes
+
+* fix typo in version 7 uuid documentation ([#153](https://github.com/google/uuid/issues/153)) ([016b199](https://github.com/google/uuid/commit/016b199544692f745ffc8867b914129ecb47ef06))
+* Monotonicity in UUIDv7 ([#150](https://github.com/google/uuid/issues/150)) ([a2b2b32](https://github.com/google/uuid/commit/a2b2b32373ff0b1a312b7fdf6d38a977099698a6))
+
+## [1.5.0](https://github.com/google/uuid/compare/v1.4.0...v1.5.0) (2023-12-12)
+
+
+### Features
+
+* Validate UUID without creating new UUID ([#141](https://github.com/google/uuid/issues/141)) ([9ee7366](https://github.com/google/uuid/commit/9ee7366e66c9ad96bab89139418a713dc584ae29))
+
 ## [1.4.0](https://github.com/google/uuid/compare/v1.3.1...v1.4.0) (2023-10-26)
 
 
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # uuid
 The uuid package generates and inspects UUIDs based on
-[RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122)
+[RFC 9562](https://datatracker.ietf.org/doc/html/rfc9562)
 and DCE 1.1: Authentication and Security Services. 
 
 This package is based on the github.com/pborman/uuid package (previously named
@@ -18,4 +18,4 @@ go get github.com/google/uuid
 
 Full `go doc` style documentation for the package can be viewed online without
 installing this package by using the GoDoc site here: 
-http://pkg.go.dev/github.com/google/uuid
+https://pkg.go.dev/github.com/google/uuid
diff --git a/doc.go b/doc.go
@@ -4,7 +4,7 @@
 
 // Package uuid generates and inspects UUIDs.
 //
-// UUIDs are based on RFC 4122 and DCE 1.1: Authentication and Security
+// UUIDs are based on RFC 9562(obsoletes RFC 4122) and DCE 1.1: Authentication and Security
 // Services.
 //
 // A UUID is a 16 byte (128 bit) array.  UUIDs may be used as keys to
diff --git a/hash.go b/hash.go
@@ -12,11 +12,17 @@ import (
 
 // Well known namespace IDs and UUIDs
 var (
-	NameSpaceDNS  = Must(Parse("6ba7b810-9dad-11d1-80b4-00c04fd430c8"))
-	NameSpaceURL  = Must(Parse("6ba7b811-9dad-11d1-80b4-00c04fd430c8"))
-	NameSpaceOID  = Must(Parse("6ba7b812-9dad-11d1-80b4-00c04fd430c8"))
-	NameSpaceX500 = Must(Parse("6ba7b814-9dad-11d1-80b4-00c04fd430c8"))
+	NameSpaceDNS  = MustParse("6ba7b810-9dad-11d1-80b4-00c04fd430c8")
+	NameSpaceURL  = MustParse("6ba7b811-9dad-11d1-80b4-00c04fd430c8")
+	NameSpaceOID  = MustParse("6ba7b812-9dad-11d1-80b4-00c04fd430c8")
+	NameSpaceX500 = MustParse("6ba7b814-9dad-11d1-80b4-00c04fd430c8")
 	Nil           UUID // empty UUID, all zeros
+
+	// The Max UUID is special form of UUID that is specified to have all 128 bits set to 1.
+	Max = UUID{
+		0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+		0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+	}
 )
 
 // NewHash returns a new UUID derived from the hash of space concatenated with
@@ -32,7 +38,7 @@ func NewHash(h hash.Hash, space UUID, data []byte, version int) UUID {
 	var uuid UUID
 	copy(uuid[:], s)
 	uuid[6] = (uuid[6] & 0x0f) | uint8((version&0xf)<<4)
-	uuid[8] = (uuid[8] & 0x3f) | 0x80 // RFC 4122 variant
+	uuid[8] = (uuid[8] & 0x3f) | 0x80 // RFC 9562 variant
 	return uuid
 }
 
diff --git a/json_test.go b/json_test.go
@@ -10,7 +10,7 @@ import (
 	"testing"
 )
 
-var testUUID = Must(Parse("f47ac10b-58cc-0372-8567-0e02b2c3d479"))
+var testUUID = MustParse("f47ac10b-58cc-0372-8567-0e02b2c3d479")
 
 func TestJSON(t *testing.T) {
 	type S struct {
diff --git a/null_test.go b/null_test.go
@@ -205,10 +205,10 @@ func TestNullUUIDUnmarshalJSON(t *testing.T) {
 	var nu NullUUID
 	err := json.Unmarshal(jsonNull, &nu)
 	if err != nil || nu.Valid {
-		t.Errorf("expected nil when unmarshaling null, got %s", err)
+		t.Errorf("expected nil when unmarshalling null, got %s", err)
 	}
 	err = json.Unmarshal(jsonUUID, &nu)
 	if err != nil || !nu.Valid {
-		t.Errorf("expected nil when unmarshaling null, got %s", err)
+		t.Errorf("expected nil when unmarshalling null, got %s", err)
 	}
 }
diff --git a/sql_test.go b/sql_test.go
@@ -15,7 +15,7 @@ func TestScan(t *testing.T) {
 	invalidTest := "f47ac10b-58cc-0372-8567-0e02b2c3d4"
 
 	byteTest := make([]byte, 16)
-	byteTestUUID := Must(Parse(stringTest))
+	byteTestUUID := MustParse(stringTest)
 	copy(byteTest, byteTestUUID[:])
 
 	// sunny day tests
@@ -105,7 +105,7 @@ func TestScan(t *testing.T) {
 
 func TestValue(t *testing.T) {
 	stringTest := "f47ac10b-58cc-0372-8567-0e02b2c3d479"
-	uuid := Must(Parse(stringTest))
+	uuid := MustParse(stringTest)
 	val, _ := uuid.Value()
 	if val != stringTest {
 		t.Error("Value() did not return expected string")
diff --git a/time.go b/time.go
@@ -113,7 +113,9 @@ func (uuid UUID) Time() Time {
 	var t Time
 	switch uuid.Version() {
 	case 6:
-		time := binary.BigEndian.Uint64(uuid[:8]) // Ignore uuid[6] version b0110
+		time := int64(binary.BigEndian.Uint32(uuid[0:4])) << 28
+		time |= int64(binary.BigEndian.Uint16(uuid[4:6])) << 12
+		time |= int64(binary.BigEndian.Uint16(uuid[6:8]) & 0xfff)
 		t = Time(time)
 	case 7:
 		time := binary.BigEndian.Uint64(uuid[:8])
diff --git a/util.go b/util.go
@@ -5,6 +5,7 @@
 package uuid
 
 import (
+	"bytes"
 	"io"
 )
 
@@ -41,3 +42,8 @@ func xtob(x1, x2 byte) (byte, bool) {
 	b2 := xvalues[x2]
 	return (b1 << 4) | b2, b1 != 255 && b2 != 255
 }
+
+// Compare returns an integer comparing two uuids lexicographically. The result will be 0 if a == b, -1 if a < b, and +1 if a > b.
+func Compare(a, b UUID) int {
+	return bytes.Compare(a[:], b[:])
+}
diff --git a/uuid.go b/uuid.go
@@ -16,7 +16,7 @@ import (
 )
 
 // A UUID is a 128 bit (16 byte) Universal Unique IDentifier as defined in RFC
-// 4122.
+// 9562.
 type UUID [16]byte
 
 // A Version represents a UUID's version.
@@ -28,12 +28,17 @@ type Variant byte
 // Constants returned by Variant.
 const (
 	Invalid   = Variant(iota) // Invalid UUID
-	RFC4122                   // The variant specified in RFC4122
+	RFC4122                   // The variant specified in RFC9562(obsoletes RFC4122).
 	Reserved                  // Reserved, NCS backward compatibility.
 	Microsoft                 // Reserved, Microsoft Corporation backward compatibility.
 	Future                    // Reserved for future definition.
 )
 
+// RFC9562 added V6 and V7 of UUID, but did not change specification of V1 and V4
+// implemented in this module. To avoid creating new major module version,
+// we still use RFC4122 for constant name.
+const Standard = RFC4122
+
 const randPoolSize = 16 * 16
 
 var (
@@ -42,22 +47,44 @@ var (
 	poolMu      sync.Mutex
 	poolPos     = randPoolSize     // protected with poolMu
 	pool        [randPoolSize]byte // protected with poolMu
+
+	ErrInvalidUUIDFormat      = errors.New("invalid UUID format")
+	ErrInvalidBracketedFormat = errors.New("invalid bracketed UUID format")
 )
 
+type URNPrefixError struct { prefix string }
+
+func (e URNPrefixError) Error() string {
+	return fmt.Sprintf("invalid urn prefix: %q", e.prefix)
+}
+
+func (e URNPrefixError) Is(target error) bool {
+	_, ok := target.(URNPrefixError)
+	return ok
+}
+
+var ErrInvalidURNPrefix = URNPrefixError{}
+
 type invalidLengthError struct{ len int }
 
 func (err invalidLengthError) Error() string {
 	return fmt.Sprintf("invalid UUID length: %d", err.len)
 }
 
+func (e invalidLengthError) Is(target error) bool {
+	_, ok := target.(invalidLengthError)
+	return ok
+}
+
+var ErrInvalidLength = invalidLengthError{}
+
 // IsInvalidLengthError is matcher function for custom error invalidLengthError
 func IsInvalidLengthError(err error) bool {
-	_, ok := err.(invalidLengthError)
-	return ok
+	return errors.Is(err, ErrInvalidLength)
 }
 
 // Parse decodes s into a UUID or returns an error if it cannot be parsed.  Both
-// the standard UUID forms defined in RFC 4122
+// the standard UUID forms defined in RFC 9562
 // (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx and
 // urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) are decoded.  In addition,
 // Parse accepts non-standard strings such as the raw hex encoding
@@ -74,7 +101,7 @@ func Parse(s string) (UUID, error) {
 	// urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 	case 36 + 9:
 		if !strings.EqualFold(s[:9], "urn:uuid:") {
-			return uuid, fmt.Errorf("invalid urn prefix: %q", s[:9])
+			return uuid, URNPrefixError{s[:9]}
 		}
 		s = s[9:]
 
@@ -88,7 +115,7 @@ func Parse(s string) (UUID, error) {
 		for i := range uuid {
 			uuid[i], ok = xtob(s[i*2], s[i*2+1])
 			if !ok {
-				return uuid, errors.New("invalid UUID format")
+				return uuid, ErrInvalidUUIDFormat
 			}
 		}
 		return uuid, nil
@@ -98,7 +125,8 @@ func Parse(s string) (UUID, error) {
 	// s is now at least 36 bytes long
 	// it must be of the form  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 	if s[8] != '-' || s[13] != '-' || s[18] != '-' || s[23] != '-' {
-		return uuid, errors.New("invalid UUID format")
+		return uuid, ErrInvalidUUIDFormat
+
 	}
 	for i, x := range [16]int{
 		0, 2, 4, 6,
@@ -109,7 +137,7 @@ func Parse(s string) (UUID, error) {
 	} {
 		v, ok := xtob(s[x], s[x+1])
 		if !ok {
-			return uuid, errors.New("invalid UUID format")
+			return uuid, ErrInvalidUUIDFormat
 		}
 		uuid[i] = v
 	}
@@ -123,7 +151,7 @@ func ParseBytes(b []byte) (UUID, error) {
 	case 36: // xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 	case 36 + 9: // urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 		if !bytes.EqualFold(b[:9], []byte("urn:uuid:")) {
-			return uuid, fmt.Errorf("invalid urn prefix: %q", b[:9])
+			return uuid, URNPrefixError{string(b[:9])}
 		}
 		b = b[9:]
 	case 36 + 2: // {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
@@ -133,7 +161,7 @@ func ParseBytes(b []byte) (UUID, error) {
 		for i := 0; i < 32; i += 2 {
 			uuid[i/2], ok = xtob(b[i], b[i+1])
 			if !ok {
-				return uuid, errors.New("invalid UUID format")
+				return uuid, ErrInvalidUUIDFormat
 			}
 		}
 		return uuid, nil
@@ -143,7 +171,7 @@ func ParseBytes(b []byte) (UUID, error) {
 	// s is now at least 36 bytes long
 	// it must be of the form  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 	if b[8] != '-' || b[13] != '-' || b[18] != '-' || b[23] != '-' {
-		return uuid, errors.New("invalid UUID format")
+		return uuid, ErrInvalidUUIDFormat
 	}
 	for i, x := range [16]int{
 		0, 2, 4, 6,
@@ -154,7 +182,7 @@ func ParseBytes(b []byte) (UUID, error) {
 	} {
 		v, ok := xtob(b[x], b[x+1])
 		if !ok {
-			return uuid, errors.New("invalid UUID format")
+			return uuid, ErrInvalidUUIDFormat
 		}
 		uuid[i] = v
 	}
@@ -186,6 +214,59 @@ func Must(uuid UUID, err error) UUID {
 	return uuid
 }
 
+// Validate returns an error if s is not a properly formatted UUID in one of the following formats:
+//   xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+//   urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+//   xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+//   {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
+// It returns an error if the format is invalid, otherwise nil.
+func Validate(s string) error {
+	switch len(s) {
+	// Standard UUID format
+	case 36:
+
+	// UUID with "urn:uuid:" prefix
+	case 36 + 9:
+		if !strings.EqualFold(s[:9], "urn:uuid:") {
+			return URNPrefixError{s[:9]}
+		}
+		s = s[9:]
+
+	// UUID enclosed in braces
+	case 36 + 2:
+		if s[0] != '{' || s[len(s)-1] != '}' {
+			return ErrInvalidBracketedFormat
+		}
+		s = s[1 : len(s)-1]
+
+	// UUID without hyphens
+	case 32:
+		for i := 0; i < len(s); i += 2 {
+			_, ok := xtob(s[i], s[i+1])
+			if !ok {
+				return ErrInvalidUUIDFormat
+			}
+		}
+
+	default:
+		return invalidLengthError{len(s)}
+	}
+
+	// Check for standard UUID format
+	if len(s) == 36 {
+		if s[8] != '-' || s[13] != '-' || s[18] != '-' || s[23] != '-' {
+			return ErrInvalidUUIDFormat
+		}
+		for _, x := range []int{0, 2, 4, 6, 9, 11, 14, 16, 19, 21, 24, 26, 28, 30, 32, 34} {
+			if _, ok := xtob(s[x], s[x+1]); !ok {
+				return ErrInvalidUUIDFormat
+			}
+		}
+	}
+
+	return nil
+}
+
 // String returns the string form of uuid, xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 // , or "" if uuid is invalid.
 func (uuid UUID) String() string {
diff --git a/uuid_test.go b/uuid_test.go
diff --git a/version6.go b/version6.go
diff --git a/version7.go b/version7.go

Original file line number	Diff line number	Diff line change
`@@ -10,7 +10,7 @@ import (`
`10`	`10`	`"testing"`
`11`	`11`	`)`
`12`	`12`
`13`		`-var testUUID = Must(Parse("f47ac10b-58cc-0372-8567-0e02b2c3d479"))`
	`13`	`+var testUUID = MustParse("f47ac10b-58cc-0372-8567-0e02b2c3d479")`
`14`	`14`
`15`	`15`	`func TestJSON(t *testing.T) {`
`16`	`16`	`type S struct {`
Original file line number	Diff line number	Diff line change
`@@ -205,10 +205,10 @@ func TestNullUUIDUnmarshalJSON(t *testing.T) {`
`205`	`205`	`var nu NullUUID`
`206`	`206`	`err := json.Unmarshal(jsonNull, &nu)`
`207`	`207`	`if err != nil \|\| nu.Valid {`
`208`		`- t.Errorf("expected nil when unmarshaling null, got %s", err)`
	`208`	`+ t.Errorf("expected nil when unmarshalling null, got %s", err)`
`209`	`209`	`}`
`210`	`210`	`err = json.Unmarshal(jsonUUID, &nu)`
`211`	`211`	`if err != nil \|\| !nu.Valid {`
`212`		`- t.Errorf("expected nil when unmarshaling null, got %s", err)`
	`212`	`+ t.Errorf("expected nil when unmarshalling null, got %s", err)`
`213`	`213`	`}`
`214`	`214`	`}`