sandflake

README

Sandflake

Decentralized, sequential, lexicographically sortable unique id

This is a work in progress, things might change quickly without notice

Features

• 128 bit
• Lexicographically sortable
• Sequential (not guarranted for future ids)
• 1.21e+24 unique ids per millisecond
• 2.81e+14 unique ids per worker per millisecond

Table of contents

• Install/Update
• Usage
• Composition
• Ports
• Inspiration
• License

Install/Update

go get -u github.com/celrenheit/sandflake

Usage

var g sandflake.Generator
id := g.Next()
fmt.Println(id)

Composition

• 48 bit: timestamp in milliseconds
• 32 bit: worker id (random at initialization)
• 24 bit: sequence number
• 24 bit: randomness

Sandflake ids do not need to wait some milliseconds for the next id if time goes backwards, it can just generate new ones and random bytes at the end should avoid any possible conflict with previous ids. In this case, the order is not guaranteed anymore.

Likewise, for future manually generated ids, the order is not guaranteed.

Ports

• Java: https://github.com/esiqveland/sandflake-java

Inspiration

• twitter/snowflake
• alizan/ulid and oklog/ulid

License

Apache 2.0

Documentation

Index

• Constants
• Variables
• func Compare(id1, id2 ID) int
• type FixedTimeGenerator
  • func NewFixedTimeGenerator(t time.Time) *FixedTimeGenerator
  • func (g *FixedTimeGenerator) Next() ID
• type Generator
  • func (g *Generator) Next() ID
• type ID
  • func MustParse(str string) ID
  • func MustParseBytes(b []byte) ID
  • func NewID(t time.Time, workerID WorkerID, seq uint32, randomBytes []byte) ID
  • func Next() ID
  • func Parse(str string) (ID, error)
  • func ParseBytes(b []byte) (ID, error)
  • func (d ID) After(other ID) bool
  • func (d ID) Before(other ID) bool
  • func (d ID) Bytes() []byte
  • func (d ID) Equal(other ID) bool
  • func (d ID) Marshal() ([]byte, error)
  • func (d ID) MarshalJSON() ([]byte, error)
  • func (d ID) MarshalText() ([]byte, error)
  • func (d ID) MarshalTo(dst []byte) (int, error)
  • func (d ID) RandomBytes() []byte
  • func (d ID) Sequence() uint32
  • func (d ID) Size() int
  • func (id ID) String() string
  • func (d ID) Time() time.Time
  • func (d *ID) Unmarshal(b []byte) error
  • func (d *ID) UnmarshalJSON(b []byte) error
  • func (d *ID) UnmarshalText(b []byte) error
  • func (d ID) WorkerID() (wid WorkerID)
• type WorkerID
  • func (w WorkerID) String() string

Constants

const (
	Size = timestampLength + workerIDLength + sequenceLength + randomLength
)

Variables

var (
	// errors
	ErrInvalidLength      = fmt.Errorf("expected length of id to be %d", encodedLen)
	ErrInvalidBytesLength = fmt.Errorf("expected length of bytes to be %d", Size)
)

Functions

func Compare

func Compare(id1, id2 ID) int

Types

type FixedTimeGenerator

type FixedTimeGenerator struct {
	// contains filtered or unexported fields
}

func NewFixedTimeGenerator

func NewFixedTimeGenerator(t time.Time) *FixedTimeGenerator

func (*FixedTimeGenerator) Next

func (g *FixedTimeGenerator) Next() ID

Next returns the next id. It returns an error if New() fails. It is safe for concurrent use.

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

func (*Generator) Next

func (g *Generator) Next() ID

Next returns the next id. It returns an error if New() fails. It is safe for concurrent use.

type ID

type ID [Size]byte

48bit: timestamp 32bit: worker id (defaults to MAC Address) 24bit: sequence number 24bit: random number

var (
	Nil   ID
	MaxID = ID{255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255}
)

func MustParse

func MustParse(str string) ID

func MustParseBytes

func MustParseBytes(b []byte) ID

func NewID

func NewID(t time.Time, workerID WorkerID, seq uint32, randomBytes []byte) ID

NewID returns a ID with the provided arguments.

func Next

func Next() ID

Next returns the next id from the global generator It is safe for concurrent use.

func Parse

func Parse(str string) (ID, error)

func ParseBytes

func ParseBytes(b []byte) (ID, error)

func (ID) After

func (d ID) After(other ID) bool

func (ID) Before

func (d ID) Before(other ID) bool

func (ID) Bytes

func (d ID) Bytes() []byte

func (ID) Equal

func (d ID) Equal(other ID) bool

func (ID) Marshal

func (d ID) Marshal() ([]byte, error)

func (ID) MarshalJSON

func (d ID) MarshalJSON() ([]byte, error)

func (ID) MarshalText

func (d ID) MarshalText() ([]byte, error)

func (ID) MarshalTo

func (d ID) MarshalTo(dst []byte) (int, error)

func (ID) RandomBytes

func (d ID) RandomBytes() []byte

RandomBytes returns the random stored in the ID

func (ID) Sequence

func (d ID) Sequence() uint32

Sequence returns the underlying sequence number

func (ID) Size

func (d ID) Size() int

func (ID) String

func (id ID) String() string

func (ID) Time

func (d ID) Time() time.Time

Time returns the underlying time

func (*ID) Unmarshal

func (d *ID) Unmarshal(b []byte) error

func (*ID) UnmarshalJSON

func (d *ID) UnmarshalJSON(b []byte) error

func (*ID) UnmarshalText

func (d *ID) UnmarshalText(b []byte) error

func (ID) WorkerID

func (d ID) WorkerID() (wid WorkerID)

WorkerID returns the underlying worker id

type WorkerID

type WorkerID [workerIDLength]byte

func (WorkerID) String

func (w WorkerID) String() string