snowflake

Documentation

Index

• Constants
• Variables
• func Decompose(id uint64) map[string]uint64
• 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 ParseIntBytes(id [8]byte) ID
  • func ParseString(id string) (ID, error)
  • func ParseUint64(id uint64) ID
  • 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) IntBytes() [8]byte
  • func (f ID) MarshalJSON() ([]byte, error)
  • func (f ID) String() string
  • func (f ID) Uint64() uint64
  • func (f *ID) UnmarshalJSON(b []byte) error
• type JSONSyntaxError
  • func (j JSONSyntaxError) Error() string
• type Node
  • func NewNode(node uint16, nodeBits, stepBits uint8) *Node
  • func (n *Node) Generate() ID
• type Settings
• type Snowflake
  • func NewSnowflake(st Settings) *Snowflake
  • func (sf *Snowflake) NextID() (uint64, error)

Constants

const (
	// Epoch is set to the twitter snowflake epoch of Nov 04 2010 01:42:54 UTC in milliseconds
	// You may customize this to set a different epoch for your application.
	Epoch int64 = 1288834974657
	// NodeBits holds the number of bits to use for Node
	// Remember, you have a total 22 bits to share between Node/Step
	NodeBits uint8 = 10

	// StepBits holds the number of bits to use for Step
	// Remember, you have a total 22 bits to share between Node/Step
	StepBits uint8 = 12
)

const (
	BitLenTime      = 39                               // bit length of time
	BitLenSequence  = 8                                // bit length of sequence number
	BitLenMachineID = 63 - BitLenTime - BitLenSequence // bit length of machine id
)

These constants are the bit lengths of Snowflake 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 uint64) map[string]uint64

Decompose returns a set of Snowflake ID parts.

Types

type ID

type ID uint64

An ID is a custom type used for a snowflake 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 snowflake ID

func ParseBase32

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

ParseBase32 parses a base32 []byte into a snowflake 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 snowflake ID

func ParseBase58

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

ParseBase58 parses a base58 []byte into a snowflake ID

func ParseBase64

func ParseBase64(id string) (ID, error)

ParseBase64 converts a base64 string into a snowflake ID

func ParseBytes

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

ParseBytes converts a byte slice into a snowflake ID

func ParseIntBytes

func ParseIntBytes(id [8]byte) ID

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

func ParseString

func ParseString(id string) (ID, error)

ParseString converts a string into a snowflake ID

func ParseUint64

func ParseUint64(id uint64) ID

ParseUint64 converts an uint64 into a snowflake ID

func (ID) Base2

func (f ID) Base2() string

Base2 returns a string base2 of the snowflake 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 snowflake ID

func (ID) Base58

func (f ID) Base58() string

Base58 returns a base58 string of the snowflake ID

func (ID) Base64

func (f ID) Base64() string

Base64 returns a base64 string of the snowflake ID

func (ID) Bytes

func (f ID) Bytes() []byte

Bytes returns a byte slice of the snowflake ID

func (ID) IntBytes

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

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

func (ID) MarshalJSON

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

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

func (ID) String

func (f ID) String() string

String returns a string of the snowflake ID

func (ID) Uint64

func (f ID) Uint64() uint64

Uint64 returns an int64 of the snowflake ID

func (*ID) UnmarshalJSON

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

UnmarshalJSON converts a json byte array of a snowflake 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 Node

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

A Node struct holds the basic information needed for a snowflake generator node

func NewNode

func NewNode(node uint16, nodeBits, stepBits uint8) *Node

NewNode returns a new snowflake node that can be used to generate snowflake IDs

func (*Node) Generate

func (n *Node) Generate() ID

Generate creates and returns a unique snowflake ID To help guarantee uniqueness - Make sure your system is keeping accurate system time - Make sure you never have multiple nodes running with the same node ID

type Settings

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

Settings configures Snowflake:

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

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

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

type Snowflake

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

Snowflake is a distributed unique ID generator.

func NewSnowflake

func NewSnowflake(st Settings) *Snowflake

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

func (*Snowflake) NextID

func (sf *Snowflake) NextID() (uint64, error)

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