https://github.com/michaelherold/ksuid-ruby

K-Sortable Unique IDentifiers in Ruby
https://github.com/michaelherold/ksuid-ruby

coordination hacktoberfest ksuid ruby unique-id uuid

Last synced: 4 days ago
JSON representation

K-Sortable Unique IDentifiers in Ruby

• Host: GitHub
• URL: https://github.com/michaelherold/ksuid-ruby
• Owner: michaelherold
• License: mit
• Created: 2017-10-29T14:22:21.000Z (over 7 years ago)
• Default Branch: main
• Last Pushed: 2024-10-28T18:31:28.000Z (3 months ago)
• Last Synced: 2025-01-26T22:11:55.668Z (10 days ago)
• Topics: coordination, hacktoberfest, ksuid, ruby, unique-id, uuid
• Language: Ruby
• Homepage:
• Size: 207 KB
• Stars: 54
• Watchers: 6
• Forks: 8
• Open Issues: 4
• Metadata Files:
  • Readme: README.md
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        
# KSUID for Ruby

This is the repository that holds all KSUID for Ruby gems. What is a [KSUID]((https://github.com/segmentio/ksuid)), you ask? The original readme for the Go library does a great job of explaining what they are and how you can use them, so we excerpt it here.

---

## What is a KSUID?

KSUID is for K-Sortable Unique IDentifier. It's a way to generate globally unique IDs similar to RFC 4122 UUIDs, but contain a time component so they can be "roughly" sorted by time of creation. The remainder of the KSUID is randomly generated bytes.

## Why use KSUIDs?

Distributed systems often require unique IDs. There are numerous solutions out there for doing this, so why KSUID?

### 1. Sortable by Timestamp

Unlike the more common choice of UUIDv4, KSUIDs contain a timestamp component that allows them to be roughly sorted by generation time. This is obviously not a strong guarantee as it depends on wall clocks, but is still incredibly useful in practice.

### 2. No Coordination Required

[Snowflake IDs][1] and derivatives require coordination, which significantly increases the complexity of implementation and creates operations overhead. While RFC 4122 UUIDv1 does have a time component, there aren't enough bytes of randomness to provide strong protections against duplicate ID generation.

KSUIDs use 128-bits of pseudorandom data, which provides a 64-times larger number space than the 122-bits in the well-accepted RFC 4122 UUIDv4 standard. The additional timestamp component drives down the extremely rare chance of duplication to the point of near physical infeasibility, even assuming extreme clock skew (> 24-hours) that would cause other severe anomalies.

[1]: https://blog.twitter.com/2010/announcing-snowflake

### 3. Lexicographically Sortable, Portable Representations

The binary and string representations are lexicographically sortable, which allows them to be dropped into systems which do not natively support KSUIDs and retain their k-sortable characteristics.

The string representation is that it is base 62-encoded, so that they can "fit" anywhere alphanumeric strings are accepted.

## How do they work?

KSUIDs are 20-bytes: a 32-bit unsigned integer UTC timestamp and a 128-bit randomly generated payload. The timestamp uses big-endian encoding, to allow lexicographic sorting. The timestamp epoch is adjusted to March 5th, 2014, providing over 100 years of useful life starting at UNIX epoch + 14e8. The payload uses a cryptographically strong pseudorandom number generator.

The string representation is fixed at 27-characters encoded using a base 62 encoding that also sorts lexicographically.

---

## Contents of this repository

Currently, there are two gems available:

1. [KSUID for Ruby](ksuid/README.md) provides the main data type and handling for KSUIDs. If you want to use them outside of a database, this will be all you need.

2. [KSUID for ActiveRecord](activerecord-ksuid/README.md) handles integrating with ActiveRecord. If you're using ActiveRecord and want to serialize KSUID columns, you will want this gem.