Skip to content

Latest commit

 

History

History
170 lines (105 loc) · 7.89 KB

README.md

File metadata and controls

170 lines (105 loc) · 7.89 KB

KSUID for Ruby

Build Status Test Coverage Maintainability Inline docs

ksuid is a Ruby library that can generate and parse KSUIDs. The original readme for the Go version of KSUID does a great job of explaining what they are and how they should be used, so it is excerpted 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 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.

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.

Installation

Add this line to your application's Gemfile:

gem 'ksuid'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ksuid

Usage

To generate a KSUID for the present time, use:

ksuid = KSUID.new

If you need to parse a KSUID from a string that you received, use the conversion method:

ksuid = KSUID.from_base62(base62_string)

If you need to interpret a series of bytes that you received, use the conversion method:

ksuid = KSUID.from_bytes(bytes)

The KSUID.from_bytes method can take either a byte string or a byte array.

If you need to generate a KSUID for a specific timestamp, use:

ksuid = KSUID.new(time: time)  # where time is a Time-like object

If you need to use a faster or more secure way of generating the random payloads (or if you want the payload to be non-random data), you can configure the gem for those use cases:

KSUID.configure do |config|
  config.random_generator = -> { Random.new.bytes(16) }
end

Using with Sequel

When using Sequel, you can enable a plugin to turn a field into an auto-generated KSUID. Because Sequel favors being explicit, nearly everything about the plugin is opt-in. The only default behavior is as follows:

  1. The default column name is ksuid
  2. The field is automatically generated prior to validation

There are two steps to use KSUIDs within Sequel. First, you will need to add a column to your model for the KSUID. By default, the plugin uses string serialization for its field, which looks like this:

DB.create_table(:events) do
  String :my_field_name
end

If you wish to use a binary-serialized column, you can use the blob method:

DB.create_table(:events) do
  blob :ksuid
end

To use the KSUID plugin, activate it within your model:

class Event < Sequel::Model(:events)
  plugin :ksuid
end

During this activation, there are a few options you can choose to enable:

  • binary: true - If you prefer binary KSUIDs, you can switch from the default string serialization by specifying that you want it to be a binary field.
  • field: <my_field_name> - By default, the column is named ksuid. If you want to specify a different name, you can use the field option to name it what you like.
  • force: true - Typically, you will want to generate a KSUID when you're saving a record. If you want to ensure this happens, you can force the plugin to overwrite the field when doing the first save for a record. Note that the plugin will overwrite a manually set value in this mode.
  • wrap: true - By default, the plugin will return your KSUID in its string- (or binary-) serialized form instead of as the KSUID type. If you want to wrap the accessors for the field to make them use the KSUID type, you can tell the plugin to wrap the field.

Contributing

So you’re interested in contributing to KSUID? Check out our contributing guidelines for more information on how to do that.

Supported Ruby Versions

This library aims to support and is tested against the following Ruby versions:

  • Ruby 2.3
  • Ruby 2.4
  • JRuby 9.1

If something doesn't work on one of these versions, it's a bug.

This library may inadvertently work (or seem to work) on other Ruby versions, however support will only be provided for the versions listed above.

If you would like this library to support another Ruby version or implementation, you may volunteer to be a maintainer. Being a maintainer entails making sure all tests run and pass on that implementation. When something breaks on your implementation, you will be responsible for providing patches in a timely fashion. If critical issues for a particular implementation exist at the time of a major release, support for that Ruby version may be dropped.

Versioning

This library aims to adhere to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, that version should be immediately yanked and/or a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions. As a result of this policy, you can (and should) specify a dependency on this gem using the Pessimistic Version Constraint with two digits of precision. For example:

spec.add_dependency "ksuid", "~> 0.1"

License

The gem is available as open source under the terms of the MIT License.