randflake

README

Randflake ID

Overview

Randflake ID is a distributed, uniform, unpredictable, and unique random ID generator designed to provide robust identifier generation across multiple programming languages and environments.

Key Features

• 🌐 Multi-Language Support: Available in Go, Python, and TypeScript/JavaScript
• 🔒 Cryptographically Secure: Generates unpredictable and unique identifiers
• 🚀 High-Performance ID Generation: Optimized for lock-free operation to minimize latency and maximize throughput
• 📈 Scalable: Engineered to handle high-throughput systems with a maximum ID generation rate of 17,179,869,184 ID/s
• 🔀 Distributed-Friendly: Suitable for distributed systems and microservices
• 📊 Uniform Distribution: Ensures even spread of generated IDs

Installation

Go

go get -u gosuda.org/randflake

Python

pip install randflake

TypeScript/JavaScript

npm install randflake

Usage Examples

Go

package main

import (
    "fmt"
    "time"

    "gosuda.org/randflake"
)

func main() {
    now := time.Now().Unix()

    nodeid := int64(42)
    lease_start := int64(now)
    lease_end := int64(now + 600)
    secret := []byte("super-secret-key")

    g, err := randflake.NewGenerator(nodeid, lease_start, lease_end, secret)
    if err != nil {
        panic(err)
    }

    id, err := g.Generate()
    if err != nil {
        panic(err)
    }
    fmt.Println(id)
}

Python

import time
from randflake import Generator

now = int(time.time())

nodeid = 42
lease_start = now
lease_end = now + 600
secret = b'super-secret-key'

g = Generator(nodeid, lease_start, lease_end, secret)

uid = g.generate()
print(uid)

TypeScript/JavaScript

import { Generator } from 'randflake';

const now = Math.floor(Date.now() / 1000);

const nodeid = 42;
const lease_start = now;
const lease_end = now + 600;
const secret = new TextEncoder().encode('super-secret-key');

const generator = new Generator(nodeid, lease_start, lease_end, secret);
const uid = generator.generate();
console.log(uid);

Performance

Randflake ID is designed for high-performance scenarios, with minimal overhead in ID generation.

String Representation

Randflake ID is encoded as a base32hex string.

base32hexchars = "0123456789abcdefghijklmnopqrstuv"

original = 4594531474933654033
encoded = "3vgoe12ccb8gh"

def decode(s):
    return int(s, 32)

def encode(n):
    if n < 0:
        n += 1 << 64
    
    if n == 0:
        return "0"
    
    result = ""
    while n > 0:
        result = base32hexchars[n&0x1f] + result
        n = n // 32
    return result

assert original == decode(encode(original))
assert encode(original) == "3vgoe12ccb8gh"

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

More Information

For detailed documentation and additional resources, visit: https://gosuda.org/randflake

Documentation

Index

• Constants
• Variables
• func DecodeString(s string) (int64, error)
• func EncodeString(id int64) string
• type Generator
  • func NewGenerator(nodeID int64, leaseStart int64, leaseEnd int64, secret []byte) (*Generator, error)
  • func (g *Generator) Generate() (int64, error)
  • func (g *Generator) GenerateString() (string, error)
  • func (g *Generator) Inspect(id int64) (timestamp int64, nodeID int64, sequence int64, err error)
  • func (g *Generator) InspectString(id string) (timestamp int64, nodeID int64, sequence int64, err error)
  • func (g *Generator) UpdateLease(leaseStart, leaseEnd int64) bool

Constants

const (
	// Sunday, October 27, 2024 3:33:20 AM UTC
	RANDFLAKE_EPOCH_OFFSET = 1730000000

	// 30 bits for timestamp (lifetime of 34 years)
	RANDFLAKE_TIMESTAMP_BITS = 30
	// 17 bits for node id (max 131072 nodes)
	RANDFLAKE_NODE_BITS = 17
	// 17 bits for sequence (max 131072 sequences)
	RANDFLAKE_SEQUENCE_BITS = 17

	// Tuesday, November 5, 2058 5:10:23 PM UTC
	RANDFLAKE_MAX_TIMESTAMP = RANDFLAKE_EPOCH_OFFSET + 1<<RANDFLAKE_TIMESTAMP_BITS - 1
	// 131071 nodes
	RANDFLAKE_MAX_NODE = 1<<RANDFLAKE_NODE_BITS - 1
	// 131071 sequences
	RANDFLAKE_MAX_SEQUENCE = 1<<RANDFLAKE_SEQUENCE_BITS - 1
)

Variables

var (
	ErrRandflakeDead        = errors.New("randflake: the randflake id is dead after 34 years of lifetime")
	ErrInvalidSecret        = errors.New("randflake: invalid secret, secret must be 16 bytes long")
	ErrInvalidLease         = errors.New("randflake: invalid lease, lease expired or not started yet")
	ErrInvalidNode          = errors.New("randflake: invalid node id, node id must be between 0 and 131071")
	ErrResourceExhausted    = errors.New("randflake: resource exhausted (generator can't handle current throughput, try using multiple randflake instances)")
	ErrConsistencyViolation = errors.New("randflake: timestamp consistency violation, the current time is less than the last time")
	ErrInvalidID            = errors.New("randflake: invalid id")
)

Functions

func DecodeString

func DecodeString(s string) (int64, error)

func EncodeString

func EncodeString(id int64) string

Types

type Generator

type Generator struct {

	// TimeSource is a function that returns the current time in seconds since the epoch.
	// If TimeSource is nil, time.Now().Unix() will be used.
	TimeSource func() int64
	// contains filtered or unexported fields
}

func NewGenerator

func NewGenerator(nodeID int64, leaseStart int64, leaseEnd int64, secret []byte) (*Generator, error)

NewGenerator creates a new randflake generator.

nodeID is the node ID of the randflake generator. (must be unique in the cluster in a specific lease interval) leaseStart is the start time of the lease in seconds since the epoch. leaseEnd is the end time of the lease in seconds since the epoch. secret is the secret used to generate the randflake id. (must be 16 bytes long)

func (*Generator) Generate

func (g *Generator) Generate() (int64, error)

Generate generates a unique, encrypted ID.

func (*Generator) GenerateString

func (g *Generator) GenerateString() (string, error)

GenerateString generates a unique, encrypted ID and returns it as a string.

func (*Generator) Inspect

func (g *Generator) Inspect(id int64) (timestamp int64, nodeID int64, sequence int64, err error)

Inspect returns the timestamp, node ID, and sequence number of the given ID.

func (*Generator) InspectString

func (g *Generator) InspectString(id string) (timestamp int64, nodeID int64, sequence int64, err error)

InspectString returns the timestamp, node ID, and sequence number of the given ID.

func (*Generator) UpdateLease

func (g *Generator) UpdateLease(leaseStart, leaseEnd int64) bool

UpdateLease updates the lease end time and returns true if the lease was updated.

the leaseStart must equal to the leaseStart of the generator. the leaseEnd must be greater than the leaseStart. the leaseEnd must be less than or equal to the maximum timestamp (2058-11-05 17:10:23 UTC). the leaseEnd must be greater than the current leaseEnd.