foxid

README

FOxID

---

Unique object identifier format with the possibility of lexicographic sorting.
A Go implementation of FOxID created by Kasefuchs.

📝 Table of Contents

• About
• Getting Started
• Usage
• Specification
• Acknowledgments

🧐 About

Here at LutraCorp, we spent a long time deciding between Snowflake and ULID, but each had its own disadvantages, and in the end we decided to create our own identifier format that includes the advantages of both. FOxID is a 128-bit identifier that is encoded using Crockford's Base32 and includes timestamp, generator identifier and two security measures against duplicate identifiers.

🏁 Getting Started

Prerequisites

Go: >=1.22

Installing

$ go get -u github.com/dajeo/foxid-go

🎈 Usage

Usage examples can be found on GitHub. Reference pkg.go.dev.

📑 Specification

🪛 Structure

Bit breakdown for an FOxID e.g. 065DTQHTA65T6JGMGBCTXT9P1M (counter is 8575406, random is 15283725, datacenter is 35747 and worker is 18964) looks like this:

 000000011000101011011101010111100011101001010001 1000101110100011 0100101000010100 100000101101100110101110 111010010011011000001101
                                                                                                            |------------------------| 24-bit random
                                                                                   |------------------------|                          24-bit counter
                                                                  |----------------|                                                   16-bit worker id
                                                 |----------------|                                                                    16-bit datacenter id
                                                 |----------------+----------------|                                                   32-bit generator id
|------------------------------------------------|                                                                                     48-bit timestamp

⚙️ Components

🕒 Timestamp

UNIX-time in milliseconds since epoch.

• 48-bit unsigned integer.

🆔 Generator ID

Identifier of this generator.

Note You can combine datacenter and worker ids to get an even larger field which can contain 32-bit unsigned integers.

🖥️ Datacenter ID

Identifier of datacenter on which FOxID generator is running.

• 16-bit unsigned integer.

👷 Worker ID

Identifier of worker on which FOxID generator is running (e.g. process id).

• 16-bit unsigned integer.

🧮 Counter

Incrementing number to prevent ID conflict.

• 24-bit unsigned integer.

🎲 Random

Random number to prevent ID conflict.

• 24-bit unsigned integer.

📦 Encoding

Each FOxID is a big endian byte buffer. Which can be represented as a string using Crockford's Base32 encoding.

🎉 Acknowledgements

• ULID
• Snowflake

Documentation

Index

• Variables
• type Config
• type FOxID
  • func Empty() (id FOxID)
  • func Generate(config Config) (id FOxID)
  • func Parse(s string) (id *FOxID, err error)
  • func (id *FOxID) Bytes() []byte
  • func (id *FOxID) Counter() uint32
  • func (id *FOxID) Datacenter() uint16
  • func (id *FOxID) GenerateRandom()
  • func (id *FOxID) Generator() uint32
  • func (id *FOxID) IncrementCounter()
  • func (id *FOxID) Random() uint32
  • func (id *FOxID) SetCounter(value uint32)
  • func (id *FOxID) SetDatacenter(value uint16)
  • func (id *FOxID) SetGenerator(value uint32)
  • func (id *FOxID) SetRandom(value uint32)
  • func (id *FOxID) SetTime(t time.Time)
  • func (id *FOxID) SetTimestamp(timestamp uint64)
  • func (id *FOxID) SetWorker(value uint16)
  • func (id *FOxID) String() string
  • func (id *FOxID) Time() time.Time
  • func (id *FOxID) Timestamp() uint64
  • func (id *FOxID) Worker() uint16

Variables

var ErrInvalidFOxID = errors.New("invalid FOxID")

Types

type Config

type Config struct {
	Time       time.Time
	Generator  uint32
	Datacenter uint16
	Worker     uint16
	Counter    uint32
	Random     uint32
}

type FOxID

type FOxID [16]byte

FOxID is a unique identifier with lexicographic sorting capabilities.

func Empty

func Empty() (id FOxID)

Empty returns the new empty FOxID.

func Generate

func Generate(config Config) (id FOxID)

Generate returns the new generated FOxID.

func Parse

func Parse(s string) (id *FOxID, err error)

Parse parses FOxID from its string representation.

func (*FOxID) Bytes

func (id *FOxID) Bytes() []byte

Bytes returns a bytes slice representation of FOxID.

func (*FOxID) Counter

func (id *FOxID) Counter() uint32

Counter returns the number of generated ids encoded in the FOxID.

func (*FOxID) Datacenter

func (id *FOxID) Datacenter() uint16

Datacenter returns the datacenter id encoded in the FOxID.

func (*FOxID) GenerateRandom

func (id *FOxID) GenerateRandom()

GenerateRandom sets the random component of FOxID to random value.

func (*FOxID) Generator

func (id *FOxID) Generator() uint32

Generator returns the generator id encoded in the FOxID.

func (*FOxID) IncrementCounter

func (id *FOxID) IncrementCounter()

IncrementCounter sets the FOxID counter component to the global incrementing counter.

func (*FOxID) Random

func (id *FOxID) Random() uint32

Random returns the random value used to create the FOxID.

func (*FOxID) SetCounter

func (id *FOxID) SetCounter(value uint32)

SetCounter sets the counter component of FOxID to the given value.

func (*FOxID) SetDatacenter

func (id *FOxID) SetDatacenter(value uint16)

SetDatacenter sets the datacenter component of FOxID to the given value.

func (*FOxID) SetGenerator

func (id *FOxID) SetGenerator(value uint32)

SetGenerator sets the generator component of FOxID to the given value.

func (*FOxID) SetRandom

func (id *FOxID) SetRandom(value uint32)

SetRandom sets the random component of FOxID to the given value.

func (*FOxID) SetTime

func (id *FOxID) SetTime(t time.Time)

SetTime sets the time component of the FOxID to the given in time.Time amount of milliseconds since Unix epoch.

func (*FOxID) SetTimestamp

func (id *FOxID) SetTimestamp(timestamp uint64)

SetTimestamp sets the timestamp component to the given amount of milliseconds since Unix epoch.

func (*FOxID) SetWorker

func (id *FOxID) SetWorker(value uint16)

SetWorker sets the worker component of FOxID to the given value.

func (*FOxID) String

func (id *FOxID) String() string

String returns a lexicographically sortable string encoded FOxID.

func (*FOxID) Time

func (id *FOxID) Time() time.Time

Time returns the timestamp component encoded in the FOxID as time.Time.

func (*FOxID) Timestamp

func (id *FOxID) Timestamp() uint64

Timestamp returns the timestamp encoded in the FOxID.

func (*FOxID) Worker

func (id *FOxID) Worker() uint16

Worker returns the worker id encoded in the FOxID.