flake

README

Flake

A fork from https://github.com/sony/sonyflake

Flake is a distributed unique ID generator inspired by Twitter's Snowflake.

Differences from the original Sonyflake:

• panic instead of returning errors, as these errors are mostly non actionable and should never occur: NextID() uint64
• time units are 1 msec instead of 10
• 16 bits for a machine id,
• 6 bits for a sequence number (64 per 1 ms)
• 41 bits for time in units of 1 msec

As a result, Flake has the following advantages and disadvantages:

• The lifetime (69 years) is similar to that of Snowflake (69 years)
• It can work on more distributed machines (2^16) than Snowflake (2^10)
• It can generate 2^6 IDs per 1 msec at most in a single machine/thread

Installation

go get github.com/effective-security/xdb/pkg/flake

Usage

The function NewIDGenerator creates a new IDGenerator instance.

func NewIDGenerator(st Settings) IDGenerator

You can configure Flake by the struct Settings:

type Settings struct {
	StartTime      time.Time
	MachineID      func() (uint16, error)
	CheckMachineID func(uint16) bool
}

• StartTime is the time since which the Flake time is defined as the elapsed time. If StartTime is 0, the start time of the Sonyflake is set to "2021-01-01 00:00:00 +0000 UTC". If StartTime is ahead of the current time, Flake is not created.

• MachineID returns the unique ID of the Flake instance. If MachineID returns an error, Flake will panic. If MachineID is nil, default MachineID is used. Default MachineID returns the lower 8 bits of the private IP address.

• CheckMachineID validates the uniqueness of the machine ID. If CheckMachineID returns false, Flake will panic. If CheckMachineID is nil, no validation is done.

In order to get a new unique ID, you just have to call the method NextID.

func (sf *Flake) NextID() uint64

License

The MIT License (MIT)

Documentation

Overview

Package flake implements Snowflake, a distributed unique ID generator inspired by Twitter's Snowflake.

A Flake ID is composed of

39 bits for time in units of 10 msec
 8 bits for a sequence number
16 bits for a machine id

Index

• Constants
• Variables
• func Decompose(id uint64) map[string]uint64
• func FirstID(g IDGenerator) uint64
• func IDTime(g IDGenerator, id uint64) time.Time
• func IsTestRun() bool
• func LastID(g IDGenerator) uint64
• type Flake
  • func (sf *Flake) NextID() uint64
• type IDGenerator
  • func NewIDGenerator(st Settings) IDGenerator
• type Settings

Constants

const (
	BitLenMachineID = 16                                    // bit length of machine id, 2^16
	BitLenSequence  = 6                                     // bit length of sequence number
	BitLenTime      = 63 - BitLenMachineID - BitLenSequence // bit length of time
	MaskSequence16  = uint16(1<<BitLenSequence - 1)
	MaskSequence    = uint64(MaskSequence16) << BitLenMachineID
	MaskMachineID   = uint64(1<<BitLenMachineID - 1)

	FlakeTimeUnit = int64(1 * time.Millisecond)
)

These constants are the bit lengths of Flake ID parts.

Variables

var DefaultStartTime = time.Date(2021, 1, 1, 0, 0, 0, 0, time.UTC).UTC()

DefaultStartTime provides default start time for the Flake

var NowFunc = time.Now

NowFunc returns the current time; it's overridden in tests.

Functions

func Decompose

func Decompose(id uint64) map[string]uint64

Decompose returns a set of Flake ID parts.

func FirstID

func FirstID(g IDGenerator) uint64

FirstID returns the first ID generated by the generator.

func IDTime

func IDTime(g IDGenerator, id uint64) time.Time

IDTime returns the timestamp of the flake ID.

func IsTestRun

func IsTestRun() bool

IsTestRun returns true if the program is running in the test.

func LastID

func LastID(g IDGenerator) uint64

LastID returns the last ID generated by the generator.

Types

type Flake

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

Flake is a distributed unique ID generator.

func (*Flake) NextID

func (sf *Flake) NextID() uint64

NextID generates a next unique ID. After the Flake time overflows, NextID panics.

type IDGenerator

type IDGenerator interface {
	// NextID generates a next unique ID.
	NextID() uint64
}

IDGenerator defines an interface to generate unique ID accross the cluster

var DefaultIDGenerator IDGenerator

DefaultIDGenerator for the app

func NewIDGenerator

func NewIDGenerator(st Settings) IDGenerator

NewIDGenerator returns a new Flake configured with the given Settings. NewIDGenerator panics in the following cases: - Settings.StartTime is ahead of the current time. - Settings.MachineID returns an error. - Settings.CheckMachineID returns false.

type Settings

type Settings struct {
	StartTime      time.Time
	MachineID      func() (uint16, error)
	CheckMachineID func(uint16) bool
}

Settings configures Flake:

StartTime is the time since which the Flake time is defined as the elapsed time. If StartTime is 0, the start time of the Flake is set to "2021-01-01 00:00:00 +0000 UTC". If StartTime is ahead of the current time, Flake is not created.

MachineID returns the unique ID of the Flake instance. If MachineID returns an error, Flake is not created. If MachineID is nil, default MachineID is used. Default MachineID returns the lower 8 bits of the private IP address,

CheckMachineID validates the uniqueness of the machine ID. If CheckMachineID returns false, Flake is not created. If CheckMachineID is nil, no validation is done.