v1.0.0

Release Notes - uuid v1.0.0

This marks the first stable release of the uuid package, now implementing the finalized RFC 9562. This release includes significant API changes and improvements.

🚨 Breaking Changes

• Generation Functions Signature: All NewVx() functions (e.g., NewV1, NewV4, NewV6, NewV7, NewV8) now return UUID directly instead of (UUID, error). All implementations are now guaranteed to never fail. One exception is crypto/rand.Rand() in UUIDv4 and UUIDv7 which may panic on older Linux kernels when no random data is available.
• Removed Must() and MustString(): These helper functions are removed due to the change in NewVx() signatures.
• MAC Address Configuration: The mechanism for configuring the MAC address used in V1 and V6 has changed:
  • The UseHardwareMAC boolean variable is removed. Use the new UseHardwareMAC() function instead.
  • The RandomMAC variable is removed. Use the new SetMACAddress() function to provide a custom MAC, or rely on the auto-generated random MAC.
• Removed UUID Version 2: Support for UUIDv2 (NewV2) has been completely removed as it's not part of RFC 9562 and is rarely used.
• Go Version: Minimum required Go version increased from 1.20 to 1.24.

✨ New Features

• RFC 9562 Alignment: The package now implements the finalized RFC 9562 standard, which supersedes RFC 4122.
• UUIDv8 Support: Added NewV8(data []byte) UUID for creating custom, experimental UUIDs as defined in RFC 9562.
• MAC Configuration Functions:
  • SetMACAddress(macAddr net.HardwareAddr) error: Allows setting a specific MAC address for V1/V6 generation.
  • UseHardwareMAC() error: Attempts to find and use a hardware MAC address from the system for V1/V6 generation.
• fmt.Stringer Implementation: UUID now implements the fmt.Stringer interface, allowing it to be printed directly in its canonical string format.
• Benchmarks: Added benchmark tests for all implemented UUID generation functions (V1, V3, V4, V5, V6, V7, V8).

🚀 Improvements

• Thread Safety: UUID V1 and V6 generation is now thread-safe using atomic operations for sequence number handling.
• UUIDv7 Precision: UUID V7 generation (NewV7) now uses millisecond precision timestamp plus a fractional component derived from nanoseconds, improving time resolution and ordering for UUIDs generated within the same millisecond.
• Enhanced Parsing: ParseBytes can now parse both binary (16 bytes) and canonical string representations (36 bytes with hyphens) of UUIDs.
• Database Handling: The database/sql.Scanner (Scan) implementation is more robust and can now correctly handle UUIDs stored as binary []byte or as string []byte (or string) in the database.
• Default MAC Address: By default, a random local multicast MAC address is generated on startup for V1/V6 generation (if hardware MAC is not explicitly enabled), enhancing privacy compared to potentially using a real hardware MAC.
• Testability: Internal components like time retrieval and random data generation are now mockable, improving test reliability.
• Test Coverage:
  • Tests updated to use examples from RFC 9562 where applicable.
  • Added comprehensive tests for database/sql interface methods (Scan, Value).
  • Added tests for predefined namespace constants (NamespaceDNS, NamespaceURL, etc.).

🐛 Bug Fixes

• Scan method now correctly parses UUIDs when the database driver returns the UUID value as a byte slice containing the string representation (e.g., []byte("686e7778-...")) instead of just the raw bytes.

🗑️ Removed

• Support for UUID Version 2 (NewV2, related files and tests).
• Helper functions Must() and MustString().
• The boolean variable UseHardwareMAC and the net.HardwareAddr variable RandomMAC.