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.
- 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
Generatorcriado 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.
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.
Instalação
go get github.com/patrickbrandao/go-loghub-uuid
Uso rápido
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
}
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) }
Mais
- Mapa completo do projeto: STARTHERE.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 ¶
Constants ¶
This section is empty.
Variables ¶
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).
Functions ¶
func BinaryToString ¶
BinaryToString é um apelido explícito para o método String(): converte o binário de 128 bits na string canônica.
func GenerateString ¶
GenerateString produz um UUID em string usando o gerador padrão do pacote.
Types ¶
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.
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.
func NewGeneratorWith ¶
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.
func (*Generator) Generate ¶
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.
func (*Generator) GenerateString ¶
GenerateString produz um UUID do nível informado já no formato string canônico (8-4-4-4-12, minúsculas).
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 Time ¶
type Time struct {
Seconds int64 // timestamp Unix em segundos desde 1970-01-01 UTC
Milliseconds int // 0..999 (fração do segundo)
Microseconds int // 0..999 (fração do milissegundo) — lido de rand_a
Nanoseconds int // 0..999 (fração do microssegundo) — lido de rand_b[61:52]
}
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 ¶
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 ¶
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).
func FromString ¶
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.
func StringToBinary ¶
StringToBinary é um apelido explícito para FromString: converte a string canônica no binário de 128 bits.
func (UUID) 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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Pacote tests contém a suíte de testes funcionais, os benchmarks e utilitários de validação da biblioteca go-loghub-uuid.
|
Pacote tests contém a suíte de testes funcionais, os benchmarks e utilitários de validação da biblioteca go-loghub-uuid. |
|
benchmark-bulk
command
Comando benchmark-bulk gera 1.000.000 de UUIDv7 de cada nível e imprime um relatório de tempo e throughput.
|
Comando benchmark-bulk gera 1.000.000 de UUIDv7 de cada nível e imprime um relatório de tempo e throughput. |