xxid

package module
v0.0.0-...-f0c500d Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 25, 2020 License: MIT Imports: 17 Imported by: 0

README

Globally Unique ID Generator

godoc license

Package xxid is a globally unique id generator library derived from the awesome xid library by Olivier Poitrey.

Package xid is a globally unique id generator library, ready to safely be used directly in your server code.

Xid uses the Mongo Object ID algorithm to generate globally unique ids with a different serialization (base64) to make it shorter when transported as a string: https://docs.mongodb.org/manual/reference/object-id/

  • 4-byte value representing the seconds since the Unix epoch,
  • 3-byte machine identifier,
  • 2-byte process id, and
  • 3-byte counter, starting with a random value.

The binary representation of the id is compatible with Mongo 12 bytes Object IDs. The string representation is using base32 hex (w/o padding) for better space efficiency when stored in that form (20 bytes). The hex variant of base32 is used to retain the sortable property of the id.

For more information and updated docs abort xid, please see xid's README.

This xxid package is different from xid in following ways:

  1. xxid use 15 bytes for an ID object instead of xid's 12 bytes:

    • 4-byte value representing the seconds since epoch 15e8
    • 1-byte random or user specified flag (0-127)
    • 4-byte machine id or user specified IPv4 address
    • 2-byte pid or user specified port number
    • 4-byte counter (low 31 bits), starting with a random value

    Thus it's not compatible with either Mongo Object ID nor xid.

  2. xxid use base62 for string representation, generates 20 chars which is same length with xid, while keeping both the ID object and string representation K-ordered and sortable like xid.

  3. xxid provides a Generator type for user to specify flag, IP address and port number, this is useful to mark where the id is generated, for example, use flag for IDC, and IP address, port number for service instance.

    The flag/IP/port design enables the ability to develop coordinator-free distributed service. For example, if you have a stateful websocket server cluster which holds many client connections on different service instance, you can use xxid as an identifier for each connection. When downstream service want to talk to a client, they don't need to do an extra query to see which server the connection is on, they can get it by just checking the xxid identifier, good!

  4. xxid provides an int64 representation of an ID consisting of timestamp and counter, this is more efficient than string representation to be used inside process.

  5. xxid provides an UUID representation of an ID, which may help to work with other systems.

  6. xxid use 1 more byte for machine id, and 1 more byte for counter, thus it has smaller chance to encounter an ID collision, though you should never encounter one using the Mongo Object ID algorithm ~

Hope you enjoy this package, and any issues is welcome 😃

Install

go get github.com/jxskiss/xxid

Usage

guid := xxid.New()
fmt.Println(guid.String(), guid.UUID(), guid.Short())
// 0lZttCu0sDkrIgnwnolX 035bc246-d1f7-d050-dc15-00c8367a8bc3 121000306362977219

ip := net.ParseIP("10.9.8.7")
gen := xxid.NewGenerator().UseFlag(123).UseIP(ip).UsePort(8888)
guid = gen.New()
fmt.Println(guid.Time(), guid.Flag(), guid.MachineIP(), guid.Port())
// 2019-04-27 14:05:58 +0800 CST 123 10.9.8.7 8888

FAQ

Q: Why not using the standard Unix epoch?

A: Using a more recently epoch gives a much higher useful lifetime of around 136 years from July 2017, 15e8 was picked to be easy to remember.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidID is returned when trying to unmarshal an invalid id.
	ErrInvalidID = errors.New("xxid: invalid ID")
)

Functions

func Sort 

func Sort(ids []ID)

Sort sorts an array of IDs in-place. It works by wrapping `[]ID` and use `sort.Sort`.

func SortByMachine 

func SortByMachine(ids []ID)

SortByMachine sorts an array of IDs in-place using MachineID and Pid lexicographically. It works by wrapping `[]ID` and use `sort.Sort`.

Types

type Generator 

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

func NewGenerator 

func NewGenerator() *Generator

NewGenerator makes a new generator initialized with same machineID and pid as the package's default generator, and new random flag and counter, this is useful to specify IP, port and flag instead of the default machineID, process id and random flag. For general purpose without provided IP, port or flag, please just use the package's default functions `New` and `NewWithTime`.

func (*Generator) FromShort 

func (g *Generator) FromShort(short int64) (ID, error)

FromShort restore a short int64 id to a full unique ID.

func (*Generator) New 

func (g *Generator) New() ID

New generates a globally unique ID.

func (*Generator) NewWithTime 

func (g *Generator) NewWithTime(t time.Time) ID

NewWithTime generates a globally unique ID with the given time.

func (*Generator) UseFlag 

func (g *Generator) UseFlag(flag uint8) *Generator

func (*Generator) UseIP 

func (g *Generator) UseIP(ip net.IP) *Generator

func (*Generator) UsePort 

func (g *Generator) UsePort(port uint16) *Generator

type ID 

type ID [rawLen]byte

ID represents a unique request id, consists of - 4 bytes seconds since epoch 15e8 - 1 byte random or user specified flag - 4 bytes machine id or user specified ip address - 2 bytes pid or user specified port number - 4 bytes counter (low 31 bits)

func FromBytes 

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

FromBytes convert the byte array representation of `ID` back to `ID`.

func FromShort 

func FromShort(short int64) (ID, error)

FromShort restore a short int64 id back to a full `ID`.

func FromString 

func FromString(id string) (ID, error)

FromString reads an ID from its string representation.

func FromUUID 

func FromUUID(uuid string) (ID, error)

FromUUID reads an ID from its UUID string representation.

func New 

func New() ID

New generates a globally unique id.

func NewWithTime 

func NewWithTime(t time.Time) ID

NewWithTime generates a globally unique id with the given time.

func NilID 

func NilID() ID

NilID returns a zero value for `ID`.

func (ID) Addr 

func (id ID) Addr() string

Addr returns the v4 ip:port format of ip and port info of the id.

func (ID) Bytes 

func (id ID) Bytes() []byte

Bytes returns the byte array representation of `ID`.

func (ID) Compare 

func (id ID) Compare(other ID) int

Compare returns an integer comparing two IDs. It behaves just like `bytes.Compare`. The result will be 0 if two IDs are identical, -1 if current id is less than the other one, and 1 if current id is greater than the other.

func (ID) Counter 

func (id ID) Counter() int32

Counter returns the incrementing value part of the id. It's a runtime error to call this method with an invalid id.

func (ID) Flag 

func (id ID) Flag() uint8

Flag returns the user provided flag value. If flag is not set explicitly, it will return 0.

func (ID) IsNil 

func (id ID) IsNil() bool

IsNil Returns true if this is a "nil" ID.

func (ID) Machine 

func (id ID) Machine() []byte

Machine returns the 4-byte machine id part of the id. It's a runtime error to call this method with an invalid id.

func (ID) MachineID 

func (id ID) MachineID() uint32

MachineID returns the uint32 representation of the machine id part. It's a runtime error to call this method with an invalid id.

func (ID) MachineIP 

func (id ID) MachineIP() net.IP

MachineIP returns the IP representation of the machine id part when used with IP/PORT mode. It's a runtime error to call this method with an invalid id.

func (ID) MarshalJSON 

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

MarshalJSON implements encoding/json Marshaler interface.

func (ID) MarshalText 

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

MarshalText implements encoding/text TextMarshaler interface.

func (ID) Pid 

func (id ID) Pid() uint16

Pid returns the process id part of the id. It's a runtime error to call this method with an invalid id.

func (ID) Port 

func (id ID) Port() uint16

Port returns the port part of the id when used with IP/PORT mode. It's a runtime error to call this method with an invalid id.

func (*ID) Scan 

func (id *ID) Scan(value interface{}) (err error)

Scan implements the sql.Scanner interface.

func (ID) Short 

func (id ID) Short() int64

Short returns the 63 bits int64 representation of the ID consisting of timestamp and counter, the first bit is always 0, then the 32 bits timestamp, and the 31 bits counter.

func (ID) String 

func (id ID) String() string

String returns a base62 hex lowercased with no padding representation of the id.

func (ID) Time 

func (id ID) Time() time.Time

Time returns the timestamp part of the id. It's a runtime error to call this method with an invalid id.

func (ID) UUID 

func (id ID) UUID() string

UUID returns a UUID form representation of the id.

func (*ID) UnmarshalJSON 

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

UnmarshalJSON implements encoding/json Unmarshaler interface.

func (*ID) UnmarshalText 

func (id *ID) UnmarshalText(text []byte) error

UnmarshalText implements encoding/text TextUnmarshaler interface.

func (ID) Value 

func (id ID) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.