ksid

package
v0.0.0-...-2404884 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 12, 2025 License: MIT Imports: 11 Imported by: 0

README

ksuid Go Report Card GoDoc Circle CI

ksuid is an efficient, comprehensive, battle-tested Go library for generating and parsing a specific kind of globally unique identifier called a KSUID. This library serves as its reference implementation.

Install

go get -u github.com/segmentio/ksuid

What is a KSUID?

KSUID is for K-Sortable Unique IDentifier. It is a kind of globally unique identifier similar to a RFC 4122 UUID, built from the ground-up to be "naturally" sorted by generation timestamp without any special type-aware logic.

In short, running a set of KSUIDs through the UNIX sort command will result in a list ordered by generation time.

Why use KSUIDs?

There are numerous methods for generating unique identifiers, so why KSUID?

  1. Naturally ordered by generation time
  2. Collision-free, coordination-free, dependency-free
  3. Highly portable representations

Even if only one of these properties are important to you, KSUID is a great choice! :) Many projects chose to use KSUIDs just because the text representation is copy-and-paste friendly.

For a follow up read on the topic: A brief history of UUID

1. Naturally Ordered By Generation Time

Unlike the more ubiquitous UUIDv4, a KSUID contains a timestamp component that allows them to be loosely sorted by generation time. This is not a strong guarantee (an invariant) as it depends on wall clocks, but is still incredibly useful in practice. Both the binary and text representations will sort by creation time without any special sorting logic.

2. Collision-free, Coordination-free, Dependency-free

While RFC 4122 UUIDv1s do include a time component, there aren't enough bytes of randomness to provide strong protection against collisions (duplicates). With such a low amount of entropy, it is feasible for a malicious party to guess generated IDs, creating a problem for systems whose security is, implicitly or explicitly, sensitive to an adversary guessing identifiers.

To fit into a 64-bit number space, Snowflake IDs and its derivatives require coordination to avoid collisions, which significantly increases the deployment complexity and operational burden.

A KSUID includes 128 bits of pseudorandom data ("entropy"). This number space is 64 times larger than the 122 bits used by the well-accepted RFC 4122 UUIDv4 standard. The additional timestamp component can be considered "bonus entropy" which further decreases the probability of collisions, to the point of physical infeasibility in any practical implementation.

Highly Portable Representations

The text and binary representations are lexicographically sortable, which allows them to be dropped into systems which do not natively support KSUIDs and retain their time-ordered property.

The text representation is an alphanumeric base62 encoding, so it "fits" anywhere alphanumeric strings are accepted. No delimiters are used, so stringified KSUIDs won't be inadvertently truncated or tokenized when interpreted by software that is designed for human-readable text, a common problem for the text representation of RFC 4122 UUIDs.

How do KSUIDs work?

Binary 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 support lexicographic sorting. The timestamp epoch is adjusted to May 13th, 2014, providing over 100 years of life. The payload is generated by a cryptographically-strong pseudorandom number generator.

The text representation is always 27 characters, encoded in alphanumeric base62 that will lexicographically sort by timestamp.

High Performance

This library is designed to be used in code paths that are performance critical. Its code has been tuned to eliminate all non-essential overhead. The KSUID type is derived from a fixed-size array, which eliminates the additional reference chasing and allocation involved in a variable-width type.

The API provides an interface for use in code paths which are sensitive to allocation. For example, the Append method can be used to parse the text representation and replace the contents of a KSUID value without additional heap allocation.

All public package level "pure" functions are concurrency-safe, protected by a global mutex. For hot loops that generate a large amount of KSUIDs from a single Goroutine, the Sequence type is provided to elide the potential contention.

By default, out of an abundance of caution, the cryptographically-secure PRNG is used to generate the random bits of a KSUID. This can be relaxed in extremely performance-critical code using the included FastRander type. FastRander uses the standard PRNG with a seed generated by the cryptographically-secure PRNG.

NOTE: While there is no evidence that FastRander will increase the probability of a collision, it shouldn't be used in scenarios where uniqueness is important to security, as there is an increased chance the generated IDs can be predicted by an adversary.

Battle Tested

This code has been used in production at Segment for several years, across a diverse array of projects. Trillions upon trillions of KSUIDs have been generated in some of Segment's most performance-critical, large-scale distributed systems.

Plays Well With Others

Designed to be integrated with other libraries, the KSUID type implements many standard library interfaces, including:

  • Stringer
  • database/sql.Scanner and database/sql/driver.Valuer
  • encoding.BinaryMarshal and encoding.BinaryUnmarshal
  • encoding.TextMarshal and encoding.TextUnmarshal (encoding/json friendly!)

Command Line Tool

This package comes with a command-line tool ksuid, useful for generating KSUIDs as well as inspecting the internal components of existing KSUIDs. Machine-friendly output is provided for scripting use cases.

Given a Go build environment, it can be installed with the command:

$ go install github.com/segmentio/ksuid/cmd/ksuid

CLI Usage Examples

Generate a KSUID
$ ksuid
0ujsswThIGTUYm2K8FjOOfXtY1K
Generate 4 KSUIDs
$ ksuid -n 4
0ujsszwN8NRY24YaXiTIE2VWDTS
0ujsswThIGTUYm2K8FjOOfXtY1K
0ujssxh0cECutqzMgbtXSGnjorm
0ujsszgFvbiEr7CDgE3z8MAUPFt
Inspect the components of a KSUID
$ ksuid -f inspect 0ujtsYcgvSTl8PAuAdqWYSMnLOv

REPRESENTATION:

  String: 0ujtsYcgvSTl8PAuAdqWYSMnLOv
     Raw: 0669F7EFB5A1CD34B5F99D1154FB6853345C9735

COMPONENTS:

       Time: 2017-10-09 21:00:47 -0700 PDT
  Timestamp: 107608047
    Payload: B5A1CD34B5F99D1154FB6853345C9735
Generate a KSUID and inspect its components
$ ksuid -f inspect

REPRESENTATION:

  String: 0ujzPyRiIAffKhBux4PvQdDqMHY
     Raw: 066A029C73FC1AA3B2446246D6E89FCD909E8FE8

COMPONENTS:

       Time: 2017-10-09 21:46:20 -0700 PDT
  Timestamp: 107610780
    Payload: 73FC1AA3B2446246D6E89FCD909E8FE8
Inspect a KSUID with template formatted inspection output
$ ksuid -f template -t '{{ .Time }}: {{ .Payload }}' 0ujtsYcgvSTl8PAuAdqWYSMnLOv
2017-10-09 21:00:47 -0700 PDT: B5A1CD34B5F99D1154FB6853345C9735
Inspect multiple KSUIDs with template formatted output
$ ksuid -f template -t '{{ .Time }}: {{ .Payload }}' $(ksuid -n 4)
2017-10-09 21:05:37 -0700 PDT: 304102BC687E087CC3A811F21D113CCF
2017-10-09 21:05:37 -0700 PDT: EAF0B240A9BFA55E079D887120D962F0
2017-10-09 21:05:37 -0700 PDT: DF0761769909ABB0C7BB9D66F79FC041
2017-10-09 21:05:37 -0700 PDT: 1A8F0E3D0BDEB84A5FAD702876F46543
Generate KSUIDs and output JSON using template formatting
$ ksuid -f template -t '{ "timestamp": "{{ .Timestamp }}", "payload": "{{ .Payload }}", "ksuid": "{{.String}}"}' -n 4
{ "timestamp": "107611700", "payload": "9850EEEC191BF4FF26F99315CE43B0C8", "ksuid": "0uk1Hbc9dQ9pxyTqJ93IUrfhdGq"}
{ "timestamp": "107611700", "payload": "CC55072555316F45B8CA2D2979D3ED0A", "ksuid": "0uk1HdCJ6hUZKDgcxhpJwUl5ZEI"}
{ "timestamp": "107611700", "payload": "BA1C205D6177F0992D15EE606AE32238", "ksuid": "0uk1HcdvF0p8C20KtTfdRSB9XIm"}
{ "timestamp": "107611700", "payload": "67517BA309EA62AE7991B27BB6F2FCAC", "ksuid": "0uk1Ha7hGJ1Q9Xbnkt0yZgNwg3g"}

Implementations for other languages

License

ksuid source code is available under an MIT License.

Documentation

Index

Constants

View Source 
const (
	// EpochTimestamp KSID's epoch starts more recently so that the 32-bit number space gives a
	// significantly higher useful lifetime of around 136 years from March 2017.
	// This number (14e8) was picked to be easy to remember.
	EpochTimestamp int64 = 1400000000

	// TimestampSize is a uint32
	TimestampSize = 4

	// PayloadSize is 16-bytes
	PayloadSize = 16

	// Size KSUIDs are 20 bytes when binary encoded
	Size = TimestampSize + PayloadSize
)

Variables

View Source 
var FastRander = newRBG()

FastRander is an io.Reader that uses math/rand and is optimized for generating 16 bytes KSID payloads. It is intended to be used as a performance improvements for programs that have no need for cryptographically secure KSUIDs and are generating a lot of them.

Functions

func Compare 

func Compare(a, b KSID) int

Compare Implements comparison for KSID type

func IsSorted 

func IsSorted(ids []KSID) bool

IsSorted checks whether a slice of KSUIDs is sorted

func SetRand 

func SetRand(r io.Reader)

SetRand Sets the global source of random bytes for KSID generation. This should probably only be set once globally. While this is technically thread-safe as in it won't cause corruption, there's no guarantee on ordering.

func Sort 

func Sort(ids []KSID)

Sort Sorts the given slice of KSUIDs

Types

type CompressedSet 

type CompressedSet []byte

CompressedSet is an immutable data type which stores a set of KSUIDs.

func AppendCompressed 

func AppendCompressed(set []byte, ids ...KSID) CompressedSet

AppendCompressed uses the given byte slice as pre-allocated storage space to build a KSID set.

Note that the set uses a compression technique to store the KSUIDs, so the resulting length is not 20 x len(ids). The rule of thumb here is for the given byte slice to reserve the amount of memory that the application would be OK to waste.

func Compress 

func Compress(ids ...KSID) CompressedSet

Compress creates and returns a compressed set of KSUIDs from the list given as arguments.

func (CompressedSet) GoString 

func (set CompressedSet) GoString() string

String satisfies the fmt.GoStringer interface, returns a Go representation of the set.

func (CompressedSet) Iter 

func (set CompressedSet) Iter() CompressedSetIter

Iter returns an iterator that produces all KSUIDs in the set.

func (CompressedSet) String 

func (set CompressedSet) String() string

String satisfies the fmt.Stringer interface, returns a human-readable string representation of the set.

type CompressedSetIter 

type CompressedSetIter struct {

	// KSUID is modified by calls to the Next method to hold the KSUID loaded
	// by the iterator.
	KSUID KSID
	// contains filtered or unexported fields
}

CompressedSetIter is an iterator type returned by Set.Iter to produce the list of KSUIDs stored in a set.

Here's is how the iterator type is commonly used: 

for it := set.Iter(); it.Next(); {
	id := it.KSID
	// ...
}

CompressedSetIter values are not safe to use concurrently from multiple goroutines.

func (*CompressedSetIter) Next 

func (it *CompressedSetIter) Next() bool

Next moves the iterator forward, returning true if there a KSID was found, or false if the iterator as reached the end of the set it was created from.

type Config 

type Config struct {
	KSID
	PayloadSet   bool
	RandomSet    bool
	TimestampSet bool
}

type ConfigFn 

type ConfigFn func(*Config)

func WithBytes 

func WithBytes(t []byte) ConfigFn

func WithRandom 

func WithRandom(t []byte) ConfigFn

func WithTime 

func WithTime(t time.Time) ConfigFn

func WithTimeStamp 

func WithTimeStamp(t int64) ConfigFn

func WithValue 

func WithValue(t KSID) ConfigFn

type KSID 

type KSID struct {
	Error error
	Data  [Size]byte
}

KSID are 20 bytes: 

00-03 byte: uint32 be UTC timestamp with custom epoch
04-19 byte: random "payload"

var (

	// Nil Represents a completely empty (invalid) KSID
	Nil KSID
	// Max Represents the highest value a KSID can have
	Max = KSID{Data: [Size]byte{255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255}}
)

func New 

func New(fns ...ConfigFn) KSID

New generates a new KSID.

func Parse 

func Parse(s string) (KSID, error)

Parse decodes a string-encoded representation of a KSID object

func (KSID) Append 

func (i KSID) Append(b []byte) []byte

Append appends the string representation of i to b, returning a slice to a potentially larger memory area.

func (KSID) Bytes 

func (i KSID) Bytes() []byte

Bytes Raw byte representation of KSID.

func (KSID) Get 

func (i KSID) Get() interface{}

Get satisfies the flag.Getter interface, making it possible to use KSUIDs as part of the command line options of a program.

func (KSID) IsNil 

func (i KSID) IsNil() bool

IsNil returns true if this is a "nil" KSID

func (KSID) MarshalBinary 

func (i KSID) MarshalBinary() ([]byte, error)

func (KSID) MarshalText 

func (i KSID) MarshalText() ([]byte, error)

func (KSID) Next 

func (i KSID) Next() KSID

Next returns the next KSID after id.

func (KSID) Payload 

func (i KSID) Payload() []byte

Payload The 16-byte random payload without the timestamp

func (KSID) Prev 

func (i KSID) Prev() KSID

Prev returns the previoud KSID before id.

func (*KSID) Scan 

func (i *KSID) Scan(src interface{}) error

Scan implements the sql.Scanner interface. It supports converting from string, []byte, or nil into a KSID value. Attempting to convert from another type will return an error.

func (*KSID) Set 

func (i *KSID) Set(s string) error

Set satisfies the flag.Value interface, making it possible to use KSUIDs as part of the command line options of a program.

func (KSID) String 

func (i KSID) String() string

String-encoded representation that can be passed through Parse()

func (KSID) Time 

func (i KSID) Time() time.Time

Time The timestamp portion of the ID as a Time object

func (KSID) Timestamp 

func (i KSID) Timestamp() uint32

Timestamp The timestamp portion of the ID as a bare integer which is uncorrected for KSID's special epoch.

func (*KSID) UnmarshalBinary 

func (i *KSID) UnmarshalBinary(b []byte) error

func (*KSID) UnmarshalText 

func (i *KSID) UnmarshalText(b []byte) error

func (KSID) Value 

func (i KSID) Value() (driver.Value, error)

Value converts the KSID into a SQL driver value which can be used to directly use the KSID as parameter to a SQL query.

type Sequence 

type Sequence struct {
	// The seed is used as base for the KSID generator, all generated KSUIDs
	// share the same leading 18 bytes of the seed.
	Seed KSID
	// contains filtered or unexported fields
}

Sequence is a KSID generator which produces a sequence of ordered KSUIDs from a seed.

Up to 65536 KSUIDs can be generated by for a single seed.

A typical usage of a Sequence looks like this: 

seq := ksid.Sequence{
	Seed: ksid.New(),
}
id, err := seq.Next()

Sequence values are not safe to use concurrently from multiple goroutines.

func (*Sequence) Bounds 

func (seq *Sequence) Bounds() (min, max KSID)

Bounds returns the inclusive min and max bounds of the KSUIDs that may be generated by the sequence. If all ids have been generated already then the returned min value is equal to the max.

func (*Sequence) Next 

func (seq *Sequence) Next() (KSID, error)

Next produces the next KSID in the sequence, or returns an error if the sequence has been exhausted.

Source Files

View all Source files

Directories

Path Synopsis
cmd
ksuid

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.