glflake

README

glflake

A distributed unique ID generator inspired by Twitter's Snowflake

ID Format

+------------------------------------------------------------------------+
| 1 Bit Unused | 39 Bit Timestamp | 16 Bit MachineID | 8 Bit Sequence ID |
+------------------------------------------------------------------------+

39 bits for time in units of 10 msec (178 years)
16 bits for a machine id (65536 nodes, distributed machines)
 8 bits for a sequence number (0 ~ 255)

Install

go get github.com/GiterLab/glflake

Usage

package main

import (
    "fmt"
    "os"

    "github.com/GiterLab/glflake"
)

func main() {
    s := glflake.Settings{}
    // s.Init(0) // set mID, or not Init use default, Default MachineID returns the lower 16 bits of the private IP address.
    dxyid := glflake.NewGlflake(s)

    id, err := dxyid.NextID()
    if err != nil {
        fmt.Println(err)
        os.Exit(0)
    }
    fmt.Println(id, id.LeadingZerosString(19), glflake.Decompose(id))
    idBase64 := id.Base64()
    id, err = glflake.ParseBase64(idBase64)
    if err != nil {
        fmt.Println(err)
        os.Exit(0)
    }
    fmt.Println(idBase64, "-->", id)

    // 19 MAX
    fmt.Println("9223372036854775807", glflake.Decompose(glflake.ID(9223372036854775807))) // 178 years
}

// Output:
//
// 1931386430720256 0001931386430720256 map[id:1931386430720256 machine-id:8329 msb:0 sequence:0 time:115119602]
// MTkzMTM4NjQzMDcyMDI1Ng== --> 1931386430720256
// 9223372036854775807 map[id:9223372036854775807 machine-id:65535 msb:0 sequence:255 time:549755813887]

License

The MIT License (MIT)

See LICENSE for details.

Reference

• Snowflake
• Sonyflake

Documentation

Overview

Package glflake implements glflake, duoxieyun distributed unique ID generator inspired by Twitter's Snowflake.

+------------------------------------------------------------------------+ | 1 Bit Unused | 39 Bit Timestamp | 16 Bit MachineID | 8 Bit Sequence ID | +------------------------------------------------------------------------+

39 bits for time in units of 10 msec (178 years) 16 bits for a machine id (65536 nodes, distributed machines)

8 bits for a sequence number (0 ~ 255))

Index

• Constants
• Variables
• func Decompose(id ID) map[string]int64
• type GLflake
  • func NewGlflake(st Settings) *GLflake
  • func (gf *GLflake) NextID() (ID, error)
• type ID
  • func ParseBase2(id string) (ID, error)
  • func ParseBase32(b []byte) (ID, error)
  • func ParseBase36(id string) (ID, error)
  • func ParseBase58(b []byte) (ID, error)
  • func ParseBase64(id string) (ID, error)
  • func ParseBytes(id []byte) (ID, error)
  • func ParseInt64(id int64) ID
  • func ParseIntBytes(id [8]byte) ID
  • func ParseString(id string) (ID, error)
  • func (f ID) Base2() string
  • func (f ID) Base32() string
  • func (f ID) Base36() string
  • func (f ID) Base58() string
  • func (f ID) Base64() string
  • func (f ID) Bytes() []byte
  • func (f ID) Int64() int64
  • func (f ID) IntBytes() [8]byte
  • func (f ID) LeadingZerosString(zeroN uint8) string
  • func (f ID) MarshalJSON() ([]byte, error)
  • func (f ID) String() string
  • func (f *ID) UnmarshalJSON(b []byte) error
• type JSONSyntaxError
  • func (j JSONSyntaxError) Error() string
• type Settings
  • func (s *Settings) Init(mID uint16)
  • func (s *Settings) StartTimeSet(t time.Time)

Constants

const (
	BitLenTime      = 39 // bit length of time
	BitLenMachineID = 16 // bit length of machineID
	BitLenSequence  = 8  // bit length of sequence number
)

These constants are the bit lengths of glflake ID parts.

Variables

var ErrInvalidBase32 = errors.New("invalid base32")

ErrInvalidBase32 is returned by ParseBase32 when given an invalid []byte

var ErrInvalidBase58 = errors.New("invalid base58")

ErrInvalidBase58 is returned by ParseBase58 when given an invalid []byte

Functions

func Decompose

func Decompose(id ID) map[string]int64

Decompose returns a set of glflake ID parts.

Types

type GLflake

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

GLflake is a distributed unique ID generator.

func NewGlflake

func NewGlflake(st Settings) *GLflake

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

func (*GLflake) NextID

func (gf *GLflake) NextID() (ID, error)

NextID generates a next unique ID. After the GLflake time overflows, NextID returns an error.

type ID

type ID int64

An ID is a custom type used for a glflake ID. This is used so we can attach methods onto the ID.

func ParseBase2

func ParseBase2(id string) (ID, error)

ParseBase2 converts a Base2 string into a glflake ID

func ParseBase32

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

ParseBase32 parses a base32 []byte into a glflake ID NOTE: There are many different base32 implementations so becareful when doing any interoperation.

func ParseBase36

func ParseBase36(id string) (ID, error)

ParseBase36 converts a Base36 string into a glflake ID

func ParseBase58

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

ParseBase58 parses a base58 []byte into a glflake ID

func ParseBase64

func ParseBase64(id string) (ID, error)

ParseBase64 converts a base64 string into a glflake ID

func ParseBytes

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

ParseBytes converts a byte slice into a glflake ID

func ParseInt64

func ParseInt64(id int64) ID

ParseInt64 converts an int64 into a glflake ID

func ParseIntBytes

func ParseIntBytes(id [8]byte) ID

ParseIntBytes converts an array of bytes encoded as big endian integer as a glflake ID

func ParseString

func ParseString(id string) (ID, error)

ParseString converts a string into a glflake ID

func (ID) Base2

func (f ID) Base2() string

Base2 returns a string base2 of the glflake ID

func (ID) Base32

func (f ID) Base32() string

Base32 uses the z-base-32 character set but encodes and decodes similar to base58, allowing it to create an even smaller result string. NOTE: There are many different base32 implementations so becareful when doing any interoperation.

func (ID) Base36

func (f ID) Base36() string

Base36 returns a base36 string of the glflake ID

func (ID) Base58

func (f ID) Base58() string

Base58 returns a base58 string of the glflake ID

func (ID) Base64

func (f ID) Base64() string

Base64 returns a base64 string of the glflake ID

func (ID) Bytes

func (f ID) Bytes() []byte

Bytes returns a byte slice of the glflake ID

func (ID) Int64

func (f ID) Int64() int64

Int64 returns an int64 of the glflake ID

func (ID) IntBytes

func (f ID) IntBytes() [8]byte

IntBytes returns an array of bytes of the glflake ID, encoded as a big endian integer.

func (ID) LeadingZerosString

func (f ID) LeadingZerosString(zeroN uint8) string

LeadingZerosString returns a string of the glflake ID, leading zeros

func (ID) MarshalJSON

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

MarshalJSON returns a json byte array string of the glflake ID.

func (ID) String

func (f ID) String() string

String returns a string of the glflake ID

func (*ID) UnmarshalJSON

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

UnmarshalJSON converts a json byte array of a glflake ID into an ID type.

type JSONSyntaxError

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

A JSONSyntaxError is returned from UnmarshalJSON if an invalid ID is provided.

func (JSONSyntaxError) Error

func (j JSONSyntaxError) Error() string

type Settings

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

Settings configures glflake:

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

MachineID returns the unique ID of the glflake instance. If MachineID returns an error, glflake is not created. If MachineID is nil, default MachineID(0) is used.

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

func (*Settings) Init

func (s *Settings) Init(mID uint16)

Init set default MachineID & ServiceID

func (*Settings) StartTimeSet

func (s *Settings) StartTimeSet(t time.Time)

StartTimeSet set start time