Module: KSUID

Defined in:
lib/ksuid.rb,
lib/ksuid/type.rb,
lib/ksuid/utils.rb,
lib/ksuid/base62.rb,
lib/ksuid/version.rb

Overview

The K-Sortable Unique IDentifier (KSUID)

Distributed systems require unique identifiers to track events throughout their subsystems. Many algorithms for generating unique identifiers, like the Snowflake ID system, require coordination with a central authority. This is an unacceptable constraint in the face of systems that run on client devices, yet we still need to be able to generate event identifiers and roughly sort them for processing.

The KSUID optimizes this problem into a roughly sortable identifier with a high possibility space to reduce the chance of collision. KSUID uses a 32-bit timestamp with second-level precision combined with 128 bytes of random data for the “payload”. The timestamp is based on the Unix epoch, but with its base shifted forward from 1970-01-01 00:00:00 UTC to 2014-05-13 16:532:20 UTC. This is to extend the useful life of the ID format to over 100 years.

Because KSUID timestamps use seconds as their unit of precision, they are unsuitable to tasks that require extreme levels of precision. If you need microsecond-level precision, a format like ULID may be more suitable for your use case.

KSUIDs are “roughly sorted”. Practically, this means that for any given event stream, there may be some events that are ordered in a slightly different way than they actually happened. There are two reasons for this. Firstly, the format is precise to the second. This means that two events that are generated in the same second will be sorted together, but the KSUID with the smaller payload value will be sorted first. Secondly, the format is generated on the client device using its clock, so KSUID is susceptible to clock shift as well. The result of sorting the identifiers is that they will be sorted into groups of identifiers that happened in the same second according to their generating device.

Examples:

Generate a new KSUID

KSUID.new

Parse a KSUID string that you have received

KSUID.from_base62('aWgEPTl1tmebfsQzFP4bxwgy80V')

Parse a KSUID byte string that you have received

KSUID.from_bytes(
  "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF"
)

Parse a KSUID byte array that you have received

KSUID.from_bytes(
  [255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
   255, 255, 255, 255]
)

Defined Under Namespace

Modules: Base62, Utils Classes: Type

Constant Summary collapse

EPOCH_TIME =

The shift in the Unix epoch time between the standard and the KSUID base

Returns:

  • (Integer) —

    the number of seconds by which we shift the epoch

1_400_000_000
BYTES =

The number of bytes that are used to represent each part of a KSUID

Returns:

  • (Hash{Symbol => Integer}) —

    the map of data type to number of bytes

{ payload: 16, timestamp: 4, total: 20 }.freeze
STRING_LENGTH =

The number of characters in a base 62-encoded KSUID

Returns:

  • (Integer) 
27
MAX_STRING_ENCODED =

The maximum KSUID as a base 62-encoded string.

Returns:

  • (String) 
'aWgEPTl1tmebfsQzFP4bxwgy80V'
VERSION =

The version of the KSUID gem

Returns:

  • (String) 
'0.1.0'

Class Method Summary collapse

Class Method Details

.from_base62(string) ⇒ KSUID::Type

Converts a base 62-encoded string into a KSUID

Examples:

Parse a KSUID string into an object

KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')

Parameters:

  • string (String) —

    the base 62-encoded KSUID to convert into an object

Returns:

  • (KSUID::Type) —

    the KSUID generated from the string



86
87
88
89
90
91
92
 
# File 'lib/ksuid.rb', line 86

def self.from_base62(string)
  string = string.rjust(STRING_LENGTH, Base62::CHARSET[0]) if string.length < STRING_LENGTH
  int = Base62.decode(string)
  bytes = Utils.int_to_bytes(int, 160)

  from_bytes(bytes)
end

.from_bytes(bytes) ⇒ KSUID::Type

Converts a byte string or byte array into a KSUID

Examples:

Parse a KSUID byte string into an object

KSUID.from_bytes("\x06\x83\xF7\x89\x04\x9C\xC2\x15\xC0\x99\xD4+xM\xBE\x994\e\xD7\x9C")

Parameters:

  • bytes (String|Array<Integer>) —

    the byte string or array to convert into an object

Returns:



103
104
105
106
107
108
109
110
 
# File 'lib/ksuid.rb', line 103

def self.from_bytes(bytes)
  bytes = bytes.bytes if bytes.is_a?(String)

  timestamp = Utils.int_from_bytes(bytes.first(BYTES[:timestamp]))
  payload = Utils.byte_string_from_array(bytes.last(BYTES[:payload]))

  KSUID::Type.new(payload: payload, time: Time.at(timestamp + EPOCH_TIME))
end

.max ⇒ KSUID::Type

Generates the maximum KSUID as a KSUID type

Examples:

Generate the maximum KSUID

KSUID.max

Returns:

  • (KSUID::Type) —

    the maximum KSUID in both timestamp and payload



120
121
122
 
# File 'lib/ksuid.rb', line 120

def self.max
  from_bytes([255] * BYTES[:total])
end

.new(payload: nil, time: Time.now) ⇒ KSUID::Type

Instantiates a new KSUID

Examples:

Generate a new KSUID for the current second

KSUID.new

Generate a new KSUID for a given timestamp

KSUID.new(time: Time.parse('2017-11-05 15:00:04 UTC'))

Parameters:

  • payload (String|Array<Integer>|nil) (defaults to: nil) —

    the payload for the KSUID

  • time (Time) (defaults to: Time.now) —

    the timestamp to use for the KSUID

Returns:



137
138
139
 
# File 'lib/ksuid.rb', line 137

def self.new(payload: nil, time: Time.now)
  Type.new(payload: payload, time: time)
end