loghubuuid

README

go-loghub-uuid

Biblioteca Go leve e rápida para gerar UUIDv7 (RFC 9562) com três níveis de precisão temporal, conversões string⇄binário e importação das propriedades de tempo. Gera também todas as demais versões de UUID da RFC 9562 — 1, 2, 3, 4, 5, 6 e 8.

• Rápida: geração binária em dezenas de nanossegundos, zero alocações, mais de 11 mil UUIDs/ms por núcleo (em VM modesta).
• Concorrente: um único Generator criado no boot atende centenas de goroutines sem trava global.
• Sem dependências: apenas a biblioteca padrão do Go.
• Multinível: do milissegundo padrão até nanossegundos embutidos.
• Completa: todas as versões da RFC 9562, análise permissiva de texto, serialização em JSON e integração com database/sql.

Níveis

Nível	Precisão embutida	Compatível UUIDv7
Level1	milissegundos (padrão)	Sim
Level2	+ microssegundos em rand_a	Sim
Level3	+ nanossegundos em rand_b	Sim

Todos preservam versão 7 e variante RFC.

Todas as versões de UUID

Função	Versão	Base
GenerateV1	1	tempo gregoriano + nó + sequência
GenerateV2	2	versão 1 com domínio e identificador
GenerateV3	3	resumo MD5 de espaço de nomes + nome
GenerateV4	4	122 bits aleatórios
GenerateV5	5	resumo SHA-1 de espaço de nomes + nome
GenerateV6	6	versão 1 com tempo reordenado, ordenável
Generate(Level1..3)	7	tempo Unix, com os três níveis
GenerateV8	8	122 bits livres, definidos pelo chamador

As versões 1, 2 e 6 compartilham um relógio interno com trava própria. O caminho do UUIDv7 continua sem trava alguma e sem alocações.

Instalação

go get github.com/patrickbrandao/go-loghub-uuid

Uso rápido no Linux

Instalar Go (é necessário Go 1.22 ou superior; confira com go version — se a distribuição empacotar versão inferior, use o instalador oficial):

apt-get update;
apt-get install -y golang-go;

Arquivo go.mod:

module uuid-test

go 1.22

require github.com/patrickbrandao/go-loghub-uuid v0.3.0

O require acima é preenchido automaticamente pelo go get mostrado na seção de compilação; declará-lo à mão é opcional.

Arquivo test-uuid.go:

package main

import (
	"fmt"

	uuid "github.com/patrickbrandao/go-loghub-uuid"
)

func main() {
	// Gera um UUIDv7 em string (gerador padrão interno, pronto para uso).
	fmt.Println(uuid.GenerateString(uuid.Level1))
	// ex.: 019e99e3-42f0-7882-9719-2305ff84949c
}

Compilar:

go mod download;
go build -o test-uuid test-uuid.go;

Compilar (alternativa):

go get github.com/patrickbrandao/go-loghub-uuid@latest;
go mod tidy;
go build -o test-uuid test-uuid.go;

Compilar (multi plataforma):

# Windows
GOOS=windows GOARCH=amd64 go build -o test-uuid.exe test-uuid.go

# macOS
GOOS=darwin GOARCH=amd64 go build -o test-uuid test-uuid.go

# Linux (outros processadores)
GOOS=linux GOARCH=arm64 go build -o test-uuid test-uuid.go

Rodar:

./test-uuid;
    # 019e9ace-a992-79d2-9460-e33944a68428

Em serviços de alto volume, crie um gerador no boot e reutilize:

var Gen = uuid.NewGenerator()

func newID() string { return Gen.GenerateString(uuid.Level3) }

Aviso de segurança

O gerador padrão (NewGenerator, e as funções de pacote Generate, GenerateString, GenerateV4 e GenerateV8Random) usa um PRNG estatístico (PCG), não criptográfico. Os apelidos de compatibilidade New, NewString, NewRandom e NewV7 leem de crypto/rand. Quem observar alguns identificadores consegue reconstruir o estado interno e prever os seguintes; além disso, todo UUIDv7 expõe o instante de criação por construção.

Não use estes UUIDs como segredo — token de sessão, link privado, chave de recuperação ou senha de uso único. Para identificadores que precisem ser inadivinháveis, monte o gerador com entropia criptográfica:

var Gen = uuid.NewCryptoGenerator()

NewGeneratorWithReader aceita qualquer io.Reader seguro para uso concorrente, e NewGeneratorWith continua aceitando uma função que devolve 64 bits.

Como identificador de registro, chave primária ou correlação de log — o uso a que a biblioteca se destina — o gerador padrão é adequado.

Mais

• Mapa completo do projeto: STARTHERE.md
• Vindo do pacote github.com/google/uuid: docs/MIGRATION.md
• Uso rápido: docs/DEPLOY-FAST.md
• Uso completo (todas as funções): docs/DEPLOY-FULL.md
• Testes e benchmark: docs/TEST-AND-BENCHMARK.md
• Especificação de desenvolvimento (agnóstica de linguagem): docs/SPEC.md

Licença

MIT.

Documentation

Overview

Pacote loghubuuid implementa a geração de identificadores UUIDv7 (RFC 9562) com três níveis de precisão temporal.

O UUIDv7 é um identificador de 128 bits ordenável no tempo: os bits mais significativos carregam o instante de criação, de modo que a ordenação lexicográfica das strings coincide com a ordem cronológica.

Esta biblioteca estende o padrão guardando precisão sub-milissegundo dentro dos campos "aleatórios" do UUID, em três níveis:

Level1: apenas milissegundos (48 bits padrão). rand_a e rand_b
        totalmente aleatórios. Compatível 100% com UUIDv7 comum.

Level2: invade rand_a (12 bits) para guardar os microssegundos
        (0-999) do instante. rand_b continua aleatório.

Level3: invade rand_a para os microssegundos e ocupa os 10 bits
        mais altos de rand_b para os nanossegundos (0-999). Os
        52 bits restantes de rand_b continuam aleatórios.

Em todos os níveis a versão (7) e a variante (RFC) são preservadas, portanto o resultado é sempre um UUID válido.

Concorrência: o tipo Generator é seguro para uso simultâneo por centenas de goroutines. Crie um único Generator no boot da aplicação (ou use as funções de pacote, que usam um gerador padrão interno).

Index

• Variables
• func BinaryToString(u UUID) string
• func ClockSequence() int
• func GenerateString(level Level) string
• func IsInvalidLengthError(err error) bool
• func NewString() string
• func NodeID() []byte
• func SetClockSequence(seq int)
• func SetNodeID(id []byte) bool
• func Validate(s string) error
• func VariantString(v byte) string
• func VersionString(v byte) string
• type Domain
  • func (d Domain) String() string
• type Generator
  • func NewCryptoGenerator() *Generator
  • func NewGenerator() *Generator
  • func NewGeneratorWith(source func() uint64) *Generator
  • func NewGeneratorWithReader(reader io.Reader) *Generator
  • func (g *Generator) Generate(level Level) UUID
  • func (g *Generator) GenerateString(level Level) string
  • func (g *Generator) GenerateV4() UUID
  • func (g *Generator) GenerateV8() UUID
• type GregorianTime
  • func GetTime() (GregorianTime, uint16)
  • func (t GregorianTime) Time() time.Time
  • func (t GregorianTime) UnixTime() (sec, nsec int64)
• type Level
• type NullUUID
  • func (n NullUUID) MarshalBinary() ([]byte, error)
  • func (n NullUUID) MarshalJSON() ([]byte, error)
  • func (n NullUUID) MarshalText() ([]byte, error)
  • func (n *NullUUID) Scan(src any) error
  • func (n *NullUUID) UnmarshalBinary(data []byte) error
  • func (n *NullUUID) UnmarshalJSON(data []byte) error
  • func (n *NullUUID) UnmarshalText(data []byte) error
  • func (n NullUUID) Value() (driver.Value, error)
• type Time
  • func Import(s string) (Time, error)
  • func ImportBinary(u UUID) Time
• type UUID
  • func FromBytes(b []byte) (UUID, error)
  • func FromString(s string) (UUID, error)
  • func Generate(level Level) UUID
  • func GenerateHash(h hash.Hash, space UUID, name []byte, version byte) UUID
  • func GenerateV1() UUID
  • func GenerateV2(domain Domain, id uint32) UUID
  • func GenerateV2Group() UUID
  • func GenerateV2Person() UUID
  • func GenerateV3(space UUID, name []byte) UUID
  • func GenerateV4() UUID
  • func GenerateV5(space UUID, name []byte) UUID
  • func GenerateV6() UUID
  • func GenerateV8(data [16]byte) UUID
  • func GenerateV8Random() UUID
  • func Must(u UUID, err error) UUID
  • func MustParse(s string) UUID
  • func New() UUID
  • func NewDCEGroup() (UUID, error)
  • func NewDCEPerson() (UUID, error)
  • func NewDCESecurity(domain Domain, id uint32) (UUID, error)
  • func NewHash(h hash.Hash, space UUID, data []byte, version int) UUID
  • func NewMD5(space UUID, data []byte) UUID
  • func NewRandom() (u UUID, err error)
  • func NewRandomFromReader(r io.Reader) (UUID, error)
  • func NewSHA1(space UUID, data []byte) UUID
  • func NewUUID() (UUID, error)
  • func NewV6() (UUID, error)
  • func NewV7() (u UUID, err error)
  • func NewV7FromReader(r io.Reader) (UUID, error)
  • func Parse(s string) (UUID, error)
  • func ParseBytes(b []byte) (UUID, error)
  • func StringToBinary(s string) (UUID, error)
  • func (u UUID) ClockSequence() (int, bool)
  • func (u UUID) Compare(other UUID) int
  • func (u UUID) Domain() (Domain, bool)
  • func (u UUID) GregorianTime() (GregorianTime, bool)
  • func (u UUID) ID() (uint32, bool)
  • func (u UUID) IsMax() bool
  • func (u UUID) IsZero() bool
  • func (u UUID) MarshalBinary() ([]byte, error)
  • func (u UUID) MarshalText() ([]byte, error)
  • func (u UUID) NodeID() []byte
  • func (u *UUID) Scan(src any) error
  • func (u UUID) String() string
  • func (u UUID) Timestamp() (time.Time, bool)
  • func (u UUID) TimestampWithLevel(level Level) (time.Time, bool)
  • func (u UUID) URN() string
  • func (u *UUID) UnmarshalBinary(data []byte) error
  • func (u *UUID) UnmarshalText(data []byte) error
  • func (u UUID) Value() (driver.Value, error)
  • func (u UUID) Variant() byte
  • func (u UUID) Version() byte
• type UUIDs
  • func (list UUIDs) Strings() []string

Variables

var (
	// NameSpaceDNS é o espaço de nomes de domínio.
	NameSpaceDNS = MustParse("6ba7b810-9dad-11d1-80b4-00c04fd430c8")

	// NameSpaceURL é o espaço de nomes de URL.
	NameSpaceURL = MustParse("6ba7b811-9dad-11d1-80b4-00c04fd430c8")

	// NameSpaceOID é o espaço de nomes de OID da ISO.
	NameSpaceOID = MustParse("6ba7b812-9dad-11d1-80b4-00c04fd430c8")

	// NameSpaceX500 é o espaço de nomes de nome distinto X.500.
	NameSpaceX500 = MustParse("6ba7b814-9dad-11d1-80b4-00c04fd430c8")
)

Espaços de nomes conhecidos, definidos no apêndice da RFC 9562.

var (
	// ErrInvalidLength indica comprimento incompatível com todos os
	// formatos aceitos.
	ErrInvalidLength error = &formatError{"loghubuuid: comprimento invalido para string de UUID"}

	// ErrInvalidBrackets indica a forma entre chaves malformada.
	ErrInvalidBrackets error = &formatError{"loghubuuid: chaves invalidas em string de UUID"}
)

Erros mais específicos devolvidos por Parse e ParseBytes. Todos embrulham ErrInvalidFormat, portanto errors.Is(err, ErrInvalidFormat) continua verdadeiro e quem já trata o sentinela antigo não precisa mudar nada.

FromString e StringToBinary não mudaram: continuam devolvendo exatamente ErrInvalidFormat, inclusive para comparação direta com o operador de igualdade.

var ErrEntropySource = errors.New("loghubuuid: falha ao ler da fonte de entropia")

ErrEntropySource indica que a fonte de entropia informada pelo chamador não conseguiu entregar os bytes pedidos.

var ErrInvalidFormat = errors.New("loghubuuid: string de UUID em formato inválido")

ErrInvalidFormat indica que a string fornecida não está no formato canônico de UUID (8-4-4-4-12 dígitos hexadecimais).

var ErrInvalidScanType = errors.New("loghubuuid: tipo nao suportado na leitura de UUID")

ErrInvalidScanType indica que o valor lido do banco não é conversível para UUID.

var Max = UUID{
	0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
	0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
}

Max é o UUID com todos os 128 bits em um, definido pela RFC 9562 como limite superior de faixa. Não altere o valor desta variável.

Functions

func BinaryToString

func BinaryToString(u UUID) string

BinaryToString é um apelido explícito para o método String(): converte o binário de 128 bits na string canônica.

func ClockSequence

func ClockSequence() int

ClockSequence devolve a sequência de relógio de 14 bits em uso pelos geradores de versão 1, 2 e 6, inicializando-a se ainda não houver uma.

func GenerateString

func GenerateString(level Level) string

GenerateString produz um UUID em string usando o gerador padrão do pacote.

func IsInvalidLengthError

func IsInvalidLengthError(err error) bool

IsInvalidLengthError informa se o erro veio de um comprimento incorreto.

func NewString

func NewString() string

NewString produz um UUID de versão 4 com entropia criptográfica, já em formato canônico de texto.

func NodeID

func NodeID() []byte

NodeID devolve uma cópia dos 6 bytes de identificador de nó usados pelos UUIDs de versão 1, 2 e 6.

Por padrão o nó é sorteado uma única vez e marcado como aleatório. Esta biblioteca não lê interfaces de rede, para não arrastar o pacote net para dentro de quem só gera UUIDv7. Para usar um endereço MAC real, leia-o com net.Interfaces e entregue-o a SetNodeID.

func SetClockSequence

func SetClockSequence(seq int)

SetClockSequence fixa a sequência de relógio. Só os 14 bits baixos são usados. O valor -1 pede um sorteio novo.

func SetNodeID

func SetNodeID(id []byte) bool

SetNodeID fixa o identificador de nó a partir dos 6 primeiros bytes de id. Devolve falso, sem alterar nada, se id tiver menos de 6 bytes.

A chamada não mexe no piso do relógio interno: os instantes já emitidos continuam reservados, portanto reaplicar o mesmo nó nunca repete um UUIDv1 ou UUIDv6. Para descartar o adiantamento acumulado do relógio, sorteie uma sequência nova com SetClockSequence(-1).

func Validate

func Validate(s string) error

Validate informa se a string é um UUID em algum dos formatos aceitos por Parse, devolvendo apenas o erro.

func VariantString

func VariantString(v byte) string

VariantString descreve em texto o código de variante devolvido por Variant.

Variant expõe apenas os 2 bits altos do byte 8, portanto o código 3 cobre tanto a variante reservada à Microsoft quanto a reservada para uso futuro; distinguir as duas exigiria um terceiro bit.

func VersionString

func VersionString(v byte) string

VersionString descreve em texto o número de versão devolvido por Version.

Types

type Domain

type Domain byte

Domain é o domínio de identificação de um UUID de versão 2 (DCE Security), gravado no byte 9.

const (
	// Person identifica um usuário do sistema operacional.
	Person Domain = 0

	// Group identifica um grupo do sistema operacional.
	Group Domain = 1

	// Org identifica uma organização, com significado local.
	Org Domain = 2
)

func (Domain) String

func (d Domain) String() string

String descreve o domínio em texto.

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

Generator é o objeto que produz UUIDs. Deve ser criado uma única vez, no boot da aplicação, e pode ser compartilhado por muitas goroutines.

Internamente o gerador padrão mantém um pool de geradores pseudoaleatórios rápidos (PCG) — um por thread em uso — eliminando contenção de lock e permitindo gerar milhões de IDs por segundo.

O valor zero de Generator NÃO é utilizável: use NewGenerator ou NewGeneratorWith. Por segurança, um Generator sem fonte de entropia (valor zero, ou ponteiro nulo) recorre ao gerador padrão do pacote em vez de entrar em pânico.

func NewCryptoGenerator

func NewCryptoGenerator() *Generator

NewCryptoGenerator cria um Generator cuja entropia vem inteiramente de crypto/rand, tornando os bits aleatórios imprevisíveis.

É mais lento que NewGenerator, que usa PCG semeado uma única vez. Use este quando o identificador precisar resistir a quem tenta adivinhar o próximo valor. Lembre-se de que, mesmo assim, todo UUIDv7 revela o instante de criação por construção.

func NewGenerator

func NewGenerator() *Generator

NewGenerator cria um Generator rápido e seguro para concorrência.

A entropia em tempo de execução vem de geradores PCG mantidos em um sync.Pool (sem locks compartilhados). Cada PCG é semeado uma única vez, na criação, a partir de crypto/rand (alta qualidade), e depois avança de forma puramente local — barato e contention-free.

ATENÇÃO — o PCG é um gerador pseudoaleatório estatístico, NÃO criptográfico: quem observar alguns UUIDs produzidos por este gerador consegue reconstruir o estado interno e prever os seguintes. Além disso, todo UUIDv7 expõe o instante de criação por construção. Não use estes identificadores como segredo (token de sessão, link privado, chave de recuperação); para esse fim, monte o gerador com entropia criptográfica através de NewGeneratorWith.

func NewGeneratorWith

func NewGeneratorWith(source func() uint64) *Generator

NewGeneratorWith cria um Generator usando uma fonte de aleatoriedade personalizada. A função "source" deve devolver 64 bits aleatórios e PRECISA ser segura para uso concorrente (ela será chamada por várias goroutines ao mesmo tempo).

Use isto, por exemplo, para forçar entropia criptográfica (crypto/rand) em todas as gerações, abrindo mão de parte da velocidade em troca de imprevisibilidade total.

A fonte é chamada uma única vez por UUID nos níveis 2 e 3 (onde rand_a carrega o tempo) e duas vezes no nível 1.

Entra em pânico se source for nula: é um erro de configuração, que deve aparecer no boot e não na primeira geração.

func NewGeneratorWithReader

func NewGeneratorWithReader(reader io.Reader) *Generator

NewGeneratorWithReader cria um Generator que retira entropia de um io.Reader, formato usual das fontes da biblioteca padrão.

O leitor PRECISA ser seguro para uso concorrente, porque será chamado por várias goroutines ao mesmo tempo. crypto/rand.Reader satisfaz esse requisito.

Entra em pânico se reader for nulo, e também se uma leitura falhar durante a geração: uma fonte de entropia quebrada não pode degradar em silêncio para um gerador previsível.

Para a fonte criptográfica padrão, prefira NewCryptoGenerator.

func (*Generator) Generate

func (g *Generator) Generate(level Level) UUID

Generate produz um UUID binário (128 bits) do nível informado, usando o instante atual (time.Now). Níveis desconhecidos são tratados como Level1 (totalmente padrão).

Layout dos 16 bytes (big-endian):

bytes 0..5 : unix_ts_ms .......... 48 bits  (milissegundos desde epoch)
byte  6    : 0x7_ | rand_a[11:8] . versão(4) + 4 bits altos de rand_a
byte  7    : rand_a[7:0] ......... 8 bits baixos de rand_a (total 12 bits)
byte  8    : 10_ | rand_b[61:56] . variante(2) + 6 bits altos de rand_b
bytes 9..15: rand_b[55:0] ........ 56 bits restantes de rand_b (total 62 bits)

Onde, conforme o nível:

rand_a (12 bits) = microssegundos (0-999) nos níveis 2 e 3; aleatório no nível 1.
rand_b[61:52]    = nanossegundos  (0-999) no nível 3; aleatório nos níveis 1 e 2.
demais bits      = aleatórios.

O campo de 48 bits de milissegundos comporta datas até 10889-08-02. Relógios anteriores à época Unix (1970-01-01) degradam para a própria época, em vez de produzirem um timestamp corrompido.

func (*Generator) GenerateString

func (g *Generator) GenerateString(level Level) string

GenerateString produz um UUID do nível informado já no formato string canônico (8-4-4-4-12, minúsculas).

func (*Generator) GenerateV4

func (g *Generator) GenerateV4() UUID

GenerateV4 produz um UUID de versão 4: 122 bits aleatórios, sem qualquer informação de tempo, com versão e variante fixas.

A entropia vem da fonte deste Generator. No gerador padrão isso significa PCG, um gerador pseudoaleatório estatístico e previsível: não use estes identificadores como segredo. Para imprevisibilidade real, monte o gerador com NewCryptoGenerator ou NewGeneratorWithReader.

O caminho é livre de alocações, como o dos demais geradores binários.

func (*Generator) GenerateV8

func (g *Generator) GenerateV8() UUID

GenerateV8 produz um UUID de versão 8 com os 122 bits livres preenchidos pela fonte de entropia deste Generator.

No gerador padrão a fonte é PCG, estatística e previsível: não use o resultado como segredo. Veja o aviso em GenerateV4.

O resultado é indistinguível de um UUIDv4 quanto ao conteúdo; muda apenas o número de versão. Use quando precisar marcar identificadores como pertencentes a um esquema próprio.

type GregorianTime

type GregorianTime int64

GregorianTime conta intervalos de 100 nanossegundos desde 15/10/1582. É o formato do campo de tempo dos UUIDs de versão 1, 2 e 6.

func GetTime

func GetTime() (GregorianTime, uint16)

GetTime devolve o instante gregoriano corrente e a sequência de relógio em uso, avançando o relógio interno como faria uma geração de UUIDv1.

O segundo retorno traz os 14 bits da sequência com os dois bits de variante da RFC já posicionados (bit 15 ligado, bit 14 desligado), pronto para ser gravado nos bytes 8 e 9 de um UUIDv1 ou UUIDv6 — o mesmo formato devolvido pelo pacote github.com/google/uuid. Para obter apenas a sequência, mascare com 0x3FFF ou use ClockSequence.

func (GregorianTime) Time

func (t GregorianTime) Time() time.Time

Time devolve o instante como time.Time em UTC.

func (GregorianTime) UnixTime

func (t GregorianTime) UnixTime() (sec, nsec int64)

UnixTime converte o instante gregoriano para a época Unix, devolvendo segundos e a fração em nanossegundos.

type Level

type Level uint8

Level define quanta precisão temporal é embutida no UUIDv7.

const (
	// Level1 grava apenas milissegundos (48 bits). rand_a e rand_b
	// são totalmente aleatórios. É o UUIDv7 padrão da RFC 9562.
	Level1 Level = 1

	// Level2 grava milissegundos + microssegundos (0-999) em rand_a.
	Level2 Level = 2

	// Level3 grava milissegundos + microssegundos (em rand_a) +
	// nanossegundos (0-999) nos 10 bits mais altos de rand_b.
	Level3 Level = 3
)

type NullUUID

type NullUUID struct {
	UUID  UUID
	Valid bool // Valid é falso quando a coluna era NULL
}

NullUUID representa um UUID que pode ser nulo no banco de dados, no mesmo espírito de sql.NullString.

func (NullUUID) MarshalBinary

func (n NullUUID) MarshalBinary() ([]byte, error)

MarshalBinary grava os 16 bytes, ou nada quando não há valor.

func (NullUUID) MarshalJSON

func (n NullUUID) MarshalJSON() ([]byte, error)

MarshalJSON grava a string canônica, ou null quando não há valor.

func (NullUUID) MarshalText

func (n NullUUID) MarshalText() ([]byte, error)

MarshalText grava a string canônica, ou vazio quando não há valor.

func (*NullUUID) Scan

func (n *NullUUID) Scan(src any) error

Scan implementa sql.Scanner.

func (*NullUUID) UnmarshalBinary

func (n *NullUUID) UnmarshalBinary(data []byte) error

UnmarshalBinary lê 16 bytes; entrada vazia produz valor ausente.

func (*NullUUID) UnmarshalJSON

func (n *NullUUID) UnmarshalJSON(data []byte) error

UnmarshalJSON lê a string canônica, ou null.

func (*NullUUID) UnmarshalText

func (n *NullUUID) UnmarshalText(data []byte) error

UnmarshalText lê a string canônica; entrada vazia produz valor ausente.

func (NullUUID) Value

func (n NullUUID) Value() (driver.Value, error)

Value implementa driver.Valuer.

type Time

type Time struct {
	// Seconds é o timestamp Unix em segundos desde 1970-01-01 UTC.
	Seconds int64

	// Milliseconds é a fração do segundo: sempre 0..999.
	Milliseconds int

	// Microseconds é lido de rand_a. Vale 0..999 (fração do
	// milissegundo) quando o UUID é de Level2 ou Level3; em UUIDs de
	// Level1 são 12 bits aleatórios, portanto 0..4095.
	Microseconds int

	// Nanoseconds é lido de rand_b[61:52]. Vale 0..999 (fração do
	// microssegundo) quando o UUID é de Level3; em UUIDs de Level1 ou
	// Level2 são 10 bits aleatórios, portanto 0..1023.
	Nanoseconds int
}

Time reúne as propriedades temporais extraídas de um UUIDv7.

Os campos Microseconds e Nanoseconds só têm significado real se o UUID foi gerado com Level2/Level3 (micro) e Level3 (nano). Para UUIDs de Level1 esses campos contêm bits aleatórios — ainda assim, conforme a especificação, a importação os trata como tempo preciso e devolve o valor lido nos respectivos campos sem julgar a origem.

func Import

func Import(s string) (Time, error)

Import recebe um UUIDv7 em string e devolve suas propriedades de tempo (segundos, milissegundos, microssegundos e nanossegundos). Retorna ErrInvalidFormat se a string não for um UUID canônico válido.

func ImportBinary

func ImportBinary(u UUID) Time

ImportBinary extrai as propriedades de tempo de um UUID binário.

A leitura é "cega" quanto ao nível: ela sempre interpreta rand_a como microssegundos e os 10 bits altos de rand_b como nanossegundos, considerando dados aleatórios como se fossem o tempo preciso.

type UUID

type UUID [16]byte

UUID é o valor binário de 128 bits (16 bytes, big-endian / ordem de rede).

var Nil UUID

Nil é o UUID de valor zero, com os 128 bits em zero. Não altere o valor desta variável.

func FromBytes

func FromBytes(b []byte) (UUID, error)

FromBytes constrói um UUID a partir de exatamente 16 bytes em ordem de rede. Devolve ErrInvalidLength se o tamanho for outro.

func FromString

func FromString(s string) (UUID, error)

FromString interpreta uma string canônica de UUID e devolve o valor binário de 128 bits. Aceita maiúsculas ou minúsculas. Retorna ErrInvalidFormat se o tamanho, os hifens ou os dígitos forem inválidos.

Em caso de erro o UUID devolvido é sempre o valor zero: nenhum byte parcialmente decodificado vaza para o chamador.

func Generate

func Generate(level Level) UUID

Generate produz um UUID binário usando o gerador padrão do pacote.

func GenerateHash

func GenerateHash(h hash.Hash, space UUID, name []byte, version byte) UUID

GenerateHash produz um UUID baseado em nome com a função de resumo informada, gravando o número de versão pedido.

Serve para reproduzir esquemas próprios de derivação. Para as versões da RFC use GenerateV3 ou GenerateV5. Apenas os 4 bits baixos de version são aproveitados, e a variante RFC é sempre aplicada.

func GenerateV1

func GenerateV1() UUID

GenerateV1 produz um UUID de versão 1 (RFC 9562): tempo gregoriano de 60 bits, sequência de relógio de 14 bits e identificador de nó de 48 bits.

O tempo, a sequência e o nó vêm do estado compartilhado do pacote — veja SetNodeID e SetClockSequence. O relógio interno é estritamente crescente, portanto dois UUIDv1 gerados no mesmo processo nunca carregam o mesmo instante.

Layout dos 16 bytes (big-endian):

bytes 0..3 : time_low ................ 32 bits baixos do tempo
bytes 4..5 : time_mid ................ 16 bits intermediários
byte  6    : 0x1_ | time_hi[11:8] .... versão(4) + topo do tempo
byte  7    : time_hi[7:0] ............ resto do topo (12 bits ao todo)
byte  8    : 10_ | clock_seq[13:8] ... variante(2) + topo da sequência
byte  9    : clock_seq[7:0] .......... resto da sequência
bytes 10..15: node ................... 48 bits de identificador de nó

Atenção: o UUIDv1 não é ordenável lexicograficamente, porque os bits menos significativos do tempo vêm primeiro. Para ordenação cronológica use a versão 6 ou a versão 7.

Custo da ordem estrita: quando a geração é mais rápida que o tique de 100 nanossegundos, o relógio interno avança sozinho e o instante embutido fica à frente do relógio do sistema. Em rajadas longas esse adiantamento se acumula, na proporção de um tique por UUID. A RFC 9562 permite o comportamento, mas não conte com o carimbo de tempo de um UUIDv1 ou UUIDv6 como leitura fiel do relógio sob carga sustentada.

func GenerateV2

func GenerateV2(domain Domain, id uint32) UUID

GenerateV2 produz um UUID de versão 2 (DCE Security). Ele parte de um UUIDv1 e substitui dois campos: os 32 bits baixos do tempo passam a carregar o identificador local, e o byte baixo da sequência de relógio passa a carregar o domínio.

Consequência dessa troca: o UUIDv2 perde os 32 bits menos significativos do tempo, portanto o instante embutido tem resolução de poucos minutos e não deve ser lido como carimbo de tempo. Timestamp devolve falso para esta versão.

Atenção: o UUIDv2 identifica um principal — usuário, grupo ou organização — e não um evento. Os bits de tempo que sobram só mudam a cada 2^32 tiques de 100 nanossegundos, cerca de sete minutos, e o avanço de um tique por chamada do relógio interno cai justamente nos bits descartados. Portanto, chamadas repetidas com o mesmo domínio e o mesmo identificador, dentro da mesma janela, devolvem o MESMO UUID; duas chamadas consecutivas são iguais. Sem trocar a sequência de relógio, existem no máximo 64 valores distintos por janela.

A versão 2 é legado do DCE 1.1 e não é recomendada para sistemas novos.

func GenerateV2Group

func GenerateV2Group() UUID

GenerateV2Group produz um UUID de versão 2 no domínio Group usando o identificador de grupo do processo.

Em Windows a chamada de sistema devolve -1, e o identificador gravado fica sendo 0xFFFFFFFF.

func GenerateV2Person

func GenerateV2Person() UUID

GenerateV2Person produz um UUID de versão 2 no domínio Person usando o identificador de usuário do processo.

Em Windows a chamada de sistema devolve -1, e o identificador gravado fica sendo 0xFFFFFFFF.

func GenerateV3

func GenerateV3(space UUID, name []byte) UUID

GenerateV3 produz um UUID de versão 3: o resumo MD5 do espaço de nomes concatenado com o nome, com versão e variante sobrescritas.

A geração é determinística e não usa entropia: o mesmo par espaço e nome sempre devolve o mesmo UUID, em qualquer máquina e a qualquer momento. Prefira a versão 5, que usa SHA-1.

func GenerateV4

func GenerateV4() UUID

GenerateV4 produz um UUID de versão 4 usando o gerador padrão do pacote.

func GenerateV5

func GenerateV5(space UUID, name []byte) UUID

GenerateV5 produz um UUID de versão 5: os 16 primeiros bytes do resumo SHA-1 do espaço de nomes concatenado com o nome, com versão e variante sobrescritas.

A geração é determinística e não usa entropia: o mesmo par espaço e nome sempre devolve o mesmo UUID, em qualquer máquina e a qualquer momento.

func GenerateV6

func GenerateV6() UUID

GenerateV6 produz um UUID de versão 6 (RFC 9562): os mesmos campos do UUIDv1, porém com o tempo reordenado do bit mais significativo para o menos significativo, de modo que a ordenação lexicográfica coincide com a ordem cronológica.

Layout dos 16 bytes (big-endian):

bytes 0..3 : time_high ............... 32 bits altos do tempo
bytes 4..5 : time_mid ................ 16 bits intermediários
byte  6    : 0x6_ | time_low[11:8] ... versão(4) + topo dos 12 bits baixos
byte  7    : time_low[7:0] ........... resto dos 12 bits baixos
byte  8    : 10_ | clock_seq[13:8] ... variante(2) + topo da sequência
byte  9    : clock_seq[7:0] .......... resto da sequência
bytes 10..15: node ................... 48 bits de identificador de nó

A resolução do campo é de 100 nanossegundos, mais fina que a do UUIDv7 padrão. Ainda assim, prefira o UUIDv7 em bases novas: ele não expõe identificador de nó e é o recomendado pela RFC 9562.

Custo da ordem estrita: quando a geração é mais rápida que o tique de 100 nanossegundos, o relógio interno avança sozinho e o instante embutido fica à frente do relógio do sistema. Em rajadas longas esse adiantamento se acumula, na proporção de um tique por UUID. A RFC 9562 permite o comportamento, mas não conte com o carimbo de tempo de um UUIDv1 ou UUIDv6 como leitura fiel do relógio sob carga sustentada.

func GenerateV8

func GenerateV8(data [16]byte) UUID

GenerateV8 produz um UUID de versão 8: formato livre, reservado pela RFC 9562 para esquemas próprios de fornecedor.

Os 16 bytes informados são copiados como estão, e só os 6 bits de versão e variante são sobrescritos. Restam 122 bits sob controle do chamador. Nada aqui é interpretado como tempo, e a ordenação depende inteiramente do conteúdo fornecido.

func GenerateV8Random

func GenerateV8Random() UUID

GenerateV8Random produz um UUID de versão 8 aleatório usando o gerador padrão do pacote.

func Must

func Must(u UUID, err error) UUID

Must devolve u, ou entra em pânico se err não for nula. Serve para encadear com funções que devolvem par de valores.

func MustParse

func MustParse(s string) UUID

MustParse interpreta um UUID em qualquer formato aceito por Parse e entra em pânico se a string for inválida.

Destina-se a constantes do próprio código, como espaços de nomes; nunca use com entrada vinda de fora do programa.

func New

func New() UUID

New produz um UUID de versão 4 com entropia criptográfica. Entra em pânico se a leitura de crypto/rand falhar, como uuid.New de origem.

func NewDCEGroup

func NewDCEGroup() (UUID, error)

NewDCEGroup produz um UUID de versão 2 no domínio Group. O erro é sempre nulo.

func NewDCEPerson

func NewDCEPerson() (UUID, error)

NewDCEPerson produz um UUID de versão 2 no domínio Person. O erro é sempre nulo.

func NewDCESecurity

func NewDCESecurity(domain Domain, id uint32) (UUID, error)

NewDCESecurity produz um UUID de versão 2. O erro é sempre nulo.

func NewHash

func NewHash(h hash.Hash, space UUID, data []byte, version int) UUID

NewHash produz um UUID baseado em nome com a função de resumo informada.

func NewMD5

func NewMD5(space UUID, data []byte) UUID

NewMD5 produz um UUID de versão 3.

func NewRandom

func NewRandom() (u UUID, err error)

NewRandom produz um UUID de versão 4 com entropia criptográfica. Devolve ErrEntropySource se a leitura falhar.

func NewRandomFromReader

func NewRandomFromReader(r io.Reader) (UUID, error)

NewRandomFromReader produz um UUID de versão 4 com 16 bytes lidos do leitor informado.

Monta um Generator descartável a cada chamada. Para uso repetido, prefira guardar o resultado de NewGeneratorWithReader.

func NewSHA1

func NewSHA1(space UUID, data []byte) UUID

NewSHA1 produz um UUID de versão 5.

func NewUUID

func NewUUID() (UUID, error)

NewUUID produz um UUID de versão 1. O erro é sempre nulo.

func NewV6

func NewV6() (UUID, error)

NewV6 produz um UUID de versão 6. O erro é sempre nulo.

func NewV7

func NewV7() (u UUID, err error)

NewV7 produz um UUID de versão 7 padrão (Level1) com entropia criptográfica, como o pacote de origem. Devolve ErrEntropySource se a leitura falhar. Para velocidade máxima use Generate(Level1).

Para gravar precisão sub-milissegundo, use Generate com Level2 ou Level3.

func NewV7FromReader

func NewV7FromReader(r io.Reader) (UUID, error)

NewV7FromReader produz um UUID de versão 7 com 16 bytes lidos do leitor informado.

Monta um Generator descartável a cada chamada. Para uso repetido, prefira guardar o resultado de NewGeneratorWithReader.

func Parse

func Parse(s string) (UUID, error)

Parse interpreta um UUID em qualquer um dos quatro formatos usuais:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx        canônico, 36 caracteres
urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx   URN, 45 caracteres
{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}      entre chaves, 38 caracteres
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx            hexadecimal cru, 32 caracteres

Maiúsculas e minúsculas são aceitas, inclusive no prefixo URN. Em caso de erro o UUID devolvido é sempre Nil.

Use FromString quando quiser aceitar somente o formato canônico.

func ParseBytes

func ParseBytes(b []byte) (UUID, error)

ParseBytes faz o mesmo que Parse a partir de uma sequência de bytes, sem converter para string e sem alocar.

func StringToBinary

func StringToBinary(s string) (UUID, error)

StringToBinary é um apelido explícito para FromString: converte a string canônica no binário de 128 bits.

func (UUID) ClockSequence

func (u UUID) ClockSequence() (int, bool)

ClockSequence extrai a sequência de relógio dos UUIDs de versão 1, 2 e 6. Nas versões 1 e 6 ela tem 14 bits. Na versão 2 o byte baixo da sequência é ocupado pelo domínio, portanto restam apenas os 6 bits altos (0 a 63). O segundo retorno é falso para as demais versões.

func (UUID) Compare

func (u UUID) Compare(other UUID) int

Compare ordena dois UUIDs pela sequência de bytes, devolvendo -1, 0 ou 1. Para UUIDs de versão 6 ou 7 a ordem coincide com a ordem cronológica.

Para simples igualdade não é preciso chamar nada: UUID é um vetor de bytes e aceita o operador de igualdade diretamente.

func (UUID) Domain

func (u UUID) Domain() (Domain, bool)

Domain extrai o domínio de um UUID de versão 2. O segundo retorno é falso para as demais versões.

func (UUID) GregorianTime

func (u UUID) GregorianTime() (GregorianTime, bool)

GregorianTime extrai o campo de tempo dos UUIDs de versão 1 e 6, em intervalos de 100 nanossegundos desde 15/10/1582.

O segundo retorno é falso para as demais versões, inclusive a 2: o UUIDv2 sacrifica os 32 bits baixos do tempo para guardar o identificador local, e o que sobra não é um carimbo utilizável.

func (UUID) ID

func (u UUID) ID() (uint32, bool)

ID extrai o identificador local de um UUID de versão 2. O segundo retorno é falso para as demais versões.

func (UUID) IsMax

func (u UUID) IsMax() bool

IsMax informa se o UUID tem todos os bits em um.

func (UUID) IsZero

func (u UUID) IsZero() bool

IsZero informa se o UUID é o valor nulo.

func (UUID) MarshalBinary

func (u UUID) MarshalBinary() ([]byte, error)

MarshalBinary devolve os 16 bytes do UUID em ordem de rede. Implementa encoding.BinaryMarshaler.

func (UUID) MarshalText

func (u UUID) MarshalText() ([]byte, error)

MarshalText devolve a representação canônica em texto, com 36 bytes. Implementa encoding.TextMarshaler, o que faz encoding/json gravar o UUID como string.

func (UUID) NodeID

func (u UUID) NodeID() []byte

NodeID extrai uma cópia dos 6 bytes de identificador de nó dos UUIDs de versão 1, 2 e 6. Devolve nulo para as demais versões.

func (*UUID) Scan

func (u *UUID) Scan(src any) error

Scan lê um UUID vindo do banco de dados, implementando sql.Scanner.

Aceita:

nil      — grava o UUID nulo
string   — interpretado por Parse, em qualquer formato aceito
[]byte   — 16 bytes viram o valor binário; outro tamanho é texto

Em caso de erro o receptor não é alterado.

func (UUID) String

func (u UUID) String() string

String converte o UUID binário (16 bytes) na representação canônica em texto: 32 dígitos hexadecimais minúsculos agrupados como 8-4-4-4-12 e separados por hifens. Exemplo:

0192f7c5-1a2b-7c3d-8e4f-aabbccddeeff

A implementação escreve diretamente em um buffer de 36 bytes, sem alocações intermediárias, para ser barata em caminhos quentes.

Atenção: por UUID satisfazer fmt.Stringer, os verbos %x e %X do pacote fmt formatam esta string — devolvendo 72 caracteres com o hexadecimal do texto — e não os 16 bytes. Para imprimir os bytes, converta antes: fmt.Printf("%x", u[:]).

func (UUID) Timestamp

func (u UUID) Timestamp() (time.Time, bool)

Timestamp devolve o instante de criação embutido no UUID, em UTC.

Funciona para as versões 1 e 6, com resolução de 100 nanossegundos, e para a versão 7, com resolução de milissegundo. Devolve falso para as versões que não carregam tempo — 2, 3, 4, 5 e 8.

Para recuperar também os microssegundos e nanossegundos gravados pelos níveis 2 e 3 desta biblioteca, use TimestampWithLevel.

func (UUID) TimestampWithLevel

func (u UUID) TimestampWithLevel(level Level) (time.Time, bool)

TimestampWithLevel devolve o instante de criação de um UUIDv7 em UTC, reconstruindo a precisão sub-milissegundo gravada pelo nível informado.

O nível não pode ser deduzido do UUID, por isso precisa ser informado pelo chamador. Se os campos lidos estiverem fora da faixa 0 a 999 — o que denuncia bits aleatórios, e não tempo — o excedente é descartado e devolve-se apenas o milissegundo.

Devolve falso se o UUID não for de versão 7.

func (UUID) URN

func (u UUID) URN() string

URN devolve a representação como URN da RFC 8141, ou seja, a string canônica prefixada por "urn:uuid:".

func (*UUID) UnmarshalBinary

func (u *UUID) UnmarshalBinary(data []byte) error

UnmarshalBinary lê exatamente 16 bytes em ordem de rede. Implementa encoding.BinaryUnmarshaler.

Em caso de erro o receptor não é alterado.

func (*UUID) UnmarshalText

func (u *UUID) UnmarshalText(data []byte) error

UnmarshalText lê a representação em texto, aceitando os mesmos quatro formatos de Parse. Implementa encoding.TextUnmarshaler.

Em caso de erro o receptor não é alterado.

func (UUID) Value

func (u UUID) Value() (driver.Value, error)

Value entrega o UUID ao banco de dados como a string canônica, implementando driver.Valuer.

Para gravar em coluna binária de 16 bytes, passe o valor fatiado pelo chamador em vez de confiar nesta conversão.

func (UUID) Variant

func (u UUID) Variant() byte

Variant devolve os 2 bits altos do byte 8 (deve ser 0b10 = 2 = variante RFC).

func (UUID) Version

func (u UUID) Version() byte

Version devolve o nibble de versão (deve ser 7 para UUIDs gerados aqui).

type UUIDs

type UUIDs []UUID

UUIDs é uma lista de UUIDs, com conveniências para logs e consultas.

func (UUIDs) Strings

func (list UUIDs) Strings() []string

Strings converte a lista para as representações canônicas em texto.