README
¶
UUID
V7
UUID v7 is monotonic within a process and ordered by time, making it ideal for databases and distributed systems.
id, err := uuid.MakeV7()
| Field | Bit Positions | Byte Positions | Length (bits) | Description |
|---|---|---|---|---|
| unix_ts_ms | 0–47 | uuid[0:6] | 48 | 48-bit big-endian unsigned integer representing milliseconds since the Unix Epoch. |
| ver | 48–51 | uuid[6] (high nibble) | 4 | 4-bit version field, fixed to 0111 (7). |
| rand_a | 52–63 | uuid[6] (low nibble) – uuid[7] | 12 | 12-bit field for additional time precision or monotonic counter within a millisecond. |
| var | 64–65 | uuid[8] (high 2 bits) | 2 | 2-bit variant field, fixed to 10 to conform with RFC 4122. |
| rand_b | 66–127 | uuid[8:16] | 62 | 62-bit cryptographically secure random field (from crypto/rand). |
V4
UUID v4 is completely random. It provides no ordering or time-based semantics — only uniqueness with extremely low collision probability (1 in 2^122).
id, err := uuid.MakeV4()
| Field | Bit Positions | Byte Positions | Length (bits) | Description |
|---|---|---|---|---|
| ver | 48–51 | uuid[6] (high nibble) | 4 | 4-bit version field, fixed to 0100 (4). |
| var | 64–65 | uuid[8] (high 2 bits) | 2 | 2-bit variant field, fixed to 10 to conform with RFC 4122. |
| rand | All others | uuid[0:6], uuid[7:8], uuid[9:16] | 122 | 122 cryptographically secure random bits (from crypto/rand). |
Errors
When the Go runtime could not read random data from crypto/rand, it usually means:
- You're running in a locked-down environment (like Docker or a VM) without
/dev/urandom - The system is out of entropy (common on headless servers or cloud instances)
/dev/urandomis missing, unreadable, or blocked by a security policy- You're on an old or broken OS with no proper random number generator
The
uuidpackage require cryptographically secure randomness. Ifcrypto/randfails, none of the UUID generation will be possible, unless you provide your own Randomio.readerin the generators.
Documentation
¶
Index ¶
- Constants
- func V7MonotonicCounter() func(now time.Time) (UInt12, error)
- type UInt12
- type UUID
- func (u UUID) Compare(o UUID) int
- func (u UUID) Equal(oth UUID) bool
- func (u UUID) IsZero() bool
- func (u UUID) Less(oth UUID) bool
- func (u UUID) MarshalJSON() ([]byte, error)
- func (u UUID) MarshalText() (text []byte, err error)
- func (u *UUID) Scan(value any) error
- func (u UUID) String() string
- func (u *UUID) UnmarshalJSON(data []byte) error
- func (u *UUID) UnmarshalText(text []byte) error
- func (u UUID) Value() (driver.Value, error)
- func (u UUID) Variant() int
- func (u UUID) Version() int
- type V4
- type V7
Examples ¶
Constants ¶
const ErrParse errorkitlite.Error = "uuid parse error"
Variables ¶
This section is empty.
Functions ¶
func V7MonotonicCounter ¶
V7MonotonicCounter returns a function that generates a monotonically increasing 16-bit counter within the current process. Using the provided timestamp, it ensures that counters are reset across millisecs.
This counter is designed to help ensure ordering of UUID v7 values within a single process, especially when nanosecond precision is available. It resets at the start of each millisecond and increments for subsequent calls within the same millisecond.
Note: This counter is not shared across processes or machines—it's strictly local to the calling process. For globally consistent ordering across distributed systems, consider using V7NanosecCounter instead.
The returned function is safe for concurrent use within the same process.
Types ¶
type UInt12 ¶
type UInt12 = uint16
func V7SubMillisecondRandA ¶
V7SubMillisecondRandA is a time package based nanosec rand_a counter for sub-millisec precision.
When the system supports nanosecond precision, using nanoseconds as a counter in a distributed environment becomes a natural and reliable choice.
Since time is generally synchronised across servers, nanoseconds can act as a globally consistent sequence; ensuring clear, ordered issuing of UUID v7 values even in a cloud native setup.
The implementation is based on RFC 9562 Method 3: "Replace Leftmost Random Bits with Increased Clock Precision"
This method uses sub-millisecond timestamp precision to fill the rand_a field, providing time-ordered values with sub-millisecond precision as specified in RFC 9562 Section 6.2.
This approach ensures monotonic ordering within the same millisecond while utilizing the full precision available from the system clock. The resulting UUIDs maintain temporal ordering even when generated in rapid succession within the same millisecond.
type UUID ¶
type UUID [16]byte
func MakeV4 ¶
MakeV4 generates a cryptographically secure UUID V4
Example ¶
package main
import (
"go.llib.dev/frameless/pkg/uuid"
)
func main() {
u, err := uuid.MakeV4()
_, _ = u, err
}
func MakeV7 ¶
MakeV7 will create a UUID v7.
Example ¶
package main
import (
"go.llib.dev/frameless/pkg/uuid"
)
func main() {
u, err := uuid.MakeV7()
_, _ = u, err
}
func Must ¶
Example ¶
package main
import (
"go.llib.dev/frameless/pkg/uuid"
)
func main() {
_ = uuid.Must(uuid.MakeV4)
_ = uuid.Must(uuid.MakeV7)
var v4 uuid.V4
_ = uuid.Must(v4.Make)
var v7 uuid.V7
_ = uuid.Must(v7.Make)
}
func Parse ¶
Parse will parse a string encoded UUID, according to RFC 4122.
Accepts UUIDs with or without hyphens; it ignores them. Trims whitespace gracefully. Rejects non-hex characters, ULIDs, Snowflakes, Base64. Preserves version and variant bits (v4=4, v7=7, all=variant 2). Treats UUIDs as 16-byte binary values — not strings or numbers. All generated UUIDs round-trip correctly through between UUID#String and uuid.Parse().
Example ¶
package main
import (
"go.llib.dev/frameless/pkg/uuid"
)
func main() {
u, err := uuid.Parse("2C0BB9BF-261E-4F9B-AD93-781ACDDF8FBF")
_, _ = u, err
}
Example (HandlesCaseInsensitiveUUIDHexValues) ¶
package main
import (
"go.llib.dev/frameless/pkg/uuid"
)
func main() {
u, err := uuid.Parse("2c0bb9bf-261e-4f9b-ad93-781acddf8fbf")
_, _ = u, err
}
Example (NonSeperatedUUID) ¶
package main
import (
"go.llib.dev/frameless/pkg/uuid"
)
func main() {
u, err := uuid.Parse("2C0BB9BF261E4F9BAD93781ACDDF8FBF")
_, _ = u, err
}
func (UUID) MarshalJSON ¶
func (UUID) MarshalText ¶
func (*UUID) Scan ¶
Scan implements sql.Scanner to allow UUID to be populated from SQL result values.
func (*UUID) UnmarshalJSON ¶
func (*UUID) UnmarshalText ¶
type V4 ¶
V4 is a generator for UUID version 4 (random) as defined by RFC 4122. The collision probability is negligible: ~1 in 2^61 per billion UUIDs generated. https://www.rfc-editor.org/rfc/rfc4122#section-4.4
------------------------------------------- field bits value ------------------------------------------- rand_a 60 random ver 4 0x4 rand_b 58 random var 2 0b10 ------------------------------------------- total 128 -------------------------------------------
type V7 ¶
V7 represents a UUID version 7, designed for monotonic ordering and time-based sorting. Timestamp precision is millisecond, with 12-bit nanosecond extension for intra-millisecond uniqueness.
https://www.rfc-editor.org/rfc/rfc9562#section-4.3
------------------------------------------- field bits value ------------------------------------------- unix_ts_ms 48 timestamp (ms since epoch) ver 4 0x7 rand_a 12 random or monotonic counter var 2 0b10 rand_b 62 cryptographically secure random ------------------------------------------- total 128 -------------------------------------------
Source Files