README
¶
Cuid2
Secure, collision-resistant ids optimized for horizontal scaling and performance. Next generation UUIDs.
This is a port of the JavaScript library @paralleldrive/cuid2, rewritten in Go.
For more information about Cuid2, including details about why and how, please refer to the original documentation.
Getting Started
With Go module support, you can add the following import statement to your code:
import "github.com/nrednav/cuid2"
and then run the following in the root of the repository to fetch the module:
go mod tidy
Alternatively, you can run the following command:
go get -u github.com/nrednav/cuid2
Usage
package main
import (
"fmt"
"github.com/nrednav/cuid2"
)
func main() {
// Generate a Cuid with default configuration
id := cuid2.Generate()
// or alternatively, provide your own configuration
generate, err := cuid2.Init(
cuid2.WithLength(32),
)
if err != nil {
fmt.Println(err.Error())
}
// This function generates an id with a length of 32
id = generate()
// Validate
cuid2.IsCuid(id)
}
Configuration
You can configure the behavior of the Cuid2 generator by providing the Init()
function a series of option functions.
package main
import (
"math/rand"
"github.com/nrednav/cuid2"
"sync/atomic"
)
// (Optional) create your own custom counter
type Counter struct {
value int64
}
func NewCounter(initialCount int64) *Counter {
return &Counter{value: initialCount}
}
func (c *Counter) Increment() int64 {
return atomic.AddInt64(&sc.value, 1)
}
func main() {
generate, err := cuid2.Init(
// Provide a custom function that generates a floating-point value between 0 and 1
cuid2.WithRandomFunc(rand.Float64),
// Adjust the length of generated id, min = 2, max = 32
cuid2.WithLength(32),
// Provide a custom fingerprint that will be used by the id generator to help prevent
// collisions when generating id's in a distributed system.
cuid2.WithFingerprint("hello world"),
// Provide a custom session counter that will be used to affect the
// entropy of successive id generation calls
cuid2.WithSessionCounter(NewCounter(0)),
)
}
Testing
Run the tests with:
go test
As with the original JavaScript library, the collision tests generate over 10 million ids in parallel across 7 CPU cores. The tests also feature a histogram analysis of the entropy range to ensure an even & random distribution.
Here's a sample distribution for one pool of generated ids:
Benchmarks
The id generation function can be benchmarked for varying id lengths.
To run a benchmark, use:
go test -run=XYZ -bench=. -benchtime=30s
Results:
Documentation
¶
Index ¶
Constants ¶
const ( DefaultIdLength int = 24 MinIdLength int = 2 MaxIdLength int = 32 // ~22k hosts before 50% chance of initial counter collision MaxSessionCount int64 = 476782367 )
Variables ¶
var Generate, _ = Init()
Generates Cuids using default config options
Functions ¶
Types ¶
type Config ¶
type Config struct {
// A custom function that can generate a floating-point value between 0 and 1
RandomFunc func() float64
// A counter that will be used to affect the entropy of successive id
// generation calls
SessionCounter Counter
// Length of the generated Cuid, min = 2, max = 32
Length int
// A unique string that will be used by the Cuid generator to help prevent
// collisions when generating Cuids in a distributed system.
Fingerprint string
}
type Option ¶
func WithFingerprint ¶
A unique string that will be used by the id generator to help prevent collisions when generating Cuids in a distributed system.
func WithRandomFunc ¶
A custom function that will generate a random floating-point value between 0 and 1
func WithSessionCounter ¶
A custom counter that will be used to affect the entropy of successive id generation calls
type SessionCounter ¶
type SessionCounter struct {
// contains filtered or unexported fields
}
func NewSessionCounter ¶
func NewSessionCounter(initialCount int64) *SessionCounter
func (*SessionCounter) Increment ¶
func (sc *SessionCounter) Increment() int64
Source Files