Scala global unique identifier (GUID) generator for large systems.

Ride uses Mongo Object ID algorithm to generate globally unique IDs with a custom base32 serialization to make it shorter when transported as a string. See docs.

Internally it consists of:

• first 4 bytes representing the seconds since the Unix epoch
• next 3 bytes are the current machine identifier (hostname)
• next 2 bytes are process ID
• the last 3 bytes are counter, starting with a random value.

The binary representation of the ID is compatible with Mongo 12 bytes Object IDs. The string representation is using base32 hex (w/o padding) for better space efficiency when stored in that form (20 bytes). The hex variant of base32 is used to retain the sortable property of the ID.

• Size: 12 bytes (96 bits). See comparison
• Guaranteed uniqueness for 16,777,216 (24 bits) IDs per second and per host/process
• Base32 hex encoded by default (20 chars when transported as printable string, sortable)
• K-ordered
• No need to set up a unique machine and/or data center ID
• Embedded time with 1 second precision
• Lock-free

In your build.sbt add

libraryDependencies += "com.github.kolotaev" %% "ride" % "$VERSION_YOU_NEED"

import com.github.kolotaev.ride.Id

val guid = Id()

println(guid)
// String => b8uhqvioith6uqnvvvq0

guid.getBytes
// => Array[Byte] = Array(90, 61, 29, 126, 88, -105, 98, 111, 106, -1, -1, -12)
// Byte representation of ID

val ids = Array.fill[Id](3) { Id() }
// Array(b8ui8kioith721fvvvj0, b8ui8kioith721fvvvjg, b8ui8kioith721fvvvk0)

val guid2 = Id("b8uhqvioith6uqnvvvq0")

println(guid == guid2)
// true. guid and guid2 are considered equal objects, since they represent the same Id value

println(s"$guid" == s"$guid2")
// true. guid and guid2 are the same strings

// Creating ID from malformed string throws IllegalArgumentException exception
val guid3 = Id("bad-string")


// Id can be reconstructed with byte-array representation (useful when you save it as bytes, for example in DB)
val guid4 = Id(Array[Byte](90, 61, 13, 107, 88, -105, 98, 106, -53, -1, -1, -3))

// Creating ID from incorrect byte-array throws IllegalArgumentException exception
val guid5 = Id(Array[Byte](90, 61, 13))

guid.time
// => java.time.LocalDateTime = 2017-12-22T23:58:06
// Local time embedded into ID

guid.pid
// => Array[Byte] = Array(88, -105, 98)
// Prints PID embedded into ID. It's a truncated version of the real PID

guid.machine
// Array[Byte] = Array(88, -105, 98)
// Stored machine identifier bytes

guid.counter
// Int = 56

Ride implements Serializable and Ordered[T].

UUIDs are 16 bytes (128 bits) and 36 chars as string representation. Twitter Snowflake IDs are 8 bytes (64 bits) but require machine/data-center configuration and/or central generator servers. Ride stands in between with 12 bytes (96 bits) and a more compact URL-safe string representation (20 chars). No configuration or central generator server is required so it can be used directly in server's code.

Approximate relative performance metrics.

The library is a JVM implementation of the awesome Golang library xid.

The source code is licensed under the MIT License.