randflake 1.8.0

A Python implementation the Randflake ID: a distributed, uniform, unpredictable, unique random ID generator.

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"

Cross-Language Test Vectors

The repository root contains test_vectors.json, generated by the Go test suite and consumed by the Go, Python, and TypeScript tests. Each vector records the secret, lease, timestamp, node ID, sequence, raw bit-packed ID, encrypted ID, and base32hex encoded ID.

The raw_id and encrypted_id values are JSON strings, not JSON numbers, so 64-bit values round-trip safely in JavaScript/TypeScript and other IEEE 754-number environments.

To regenerate the canonical vectors after an intentional algorithm change:

go test . -run TestRandflakeTestVectors -update-test-vectors

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