README
¶
ksuid
ksuid is a Go library that generated prefixed, k-sorted globally unique identifiers.
Each ksuid has a resource type and optionally an environment prefix (no environment prefix is for production use only). They are roughly sortable down to per-second resolution.
Properties of a ksuid:
- resource type and environment prefixing
- lexicographically, time sortable
- no startup co-ordination
- guaranteed unique relative to process/machine
Usage
API
ksuid is primarily a Go package to be consumed by Cuvva services, below are examples of its API usage.
To generate a ksuid with a custom resource type and for the production environment:
id := ksuid.Generate("user")
/* => ID{
Environment: "prod",
Resource: "user",
Timestamp: time.Time{"2018-09-27T15:44:10Z"},
MachineID: net.HardwareAddr{"8c:85:90:b3:c9:0f"},
ProcessID: 21086,
SequenceID: 0,
} */
To parse a single given ksuid:
id, err := ksuid.Parse([]byte("user_000000BWHKXYBQe5Dt06dsPlgJAh6"))
/*
=> ID{
Environment: "prod",
Resource: "user",
Timestamp: time.Time{"2018-09-27T15:44:10Z"},
MachineID: net.HardwareAddr{"8c:85:90:b3:c9:0f"},
ProcessID: 21086,
SequenceID: 0,
}, nil
*/
Command Line Tool
go get -u github.com/cuvva/ksuid/cmd/ksuid
ksuid provides a helper utility to generate and parse ksuid on the command line, it contains two subcommands: parse and generate.
To generate two ksuid with a custom resource type and for the production environment:
$ ksuid generate --resource=user --count=2
user_000000BWHKXYBQe5Dt06dsPlgJAh6
user_000000BWHL2JrcCYZwWda13ERyoam
To parse a single given ksuid:
$ ksuid parse user_000000BWHKXYBQe5Dt06dsPlgJAh6
ID: user_000000BWHKXYBQe5Dt06dsPlgJAh6
Resource: user
Environment: prod
Timestamp: 2018-09-27T15:44:10Z
Machine ID: 8c:85:90:b3:c9:0f
Process ID: 21086
Sequence ID: 0
How They Work
ksuid are minimum 22 bytes long when Base62 encoded, consisting of 16 bytes decoded:
- a 32-bit unix timestamp with a custom epoch of 2014-01-01T00:00:00Z
- 9 bytes of data that is unqiue per-machine
- the 16-bit process id of the generating service
- a 32-bit incrementing counter, reset every second
Optionally a ksuid has two, underscore delimited prefixes. The first prefix is optional, and is the environment in which the ksuid was generated (test, dev, git commit etc), omitting the environment identifies production only. The second prefix is the resource type (user, profile, vehicle etc) and is required.
For more information, check out our blog post on how we designed ksuid.
Documentation
¶
Index ¶
- Constants
- func SetEnvironment(environment string)
- func SetInstanceID(instanceID InstanceID)
- type DockerID
- type HardwareID
- type ID
- func (id ID) Bytes() []byte
- func (id ID) Equal(x ID) bool
- func (id ID) GetBSON() (interface{}, error)
- func (id ID) IsZero() bool
- func (id ID) MarshalJSON() ([]byte, error)
- func (id *ID) Scan(src interface{}) error
- func (id *ID) SetBSON(raw bson.Raw) error
- func (id ID) String() string
- func (id *ID) UnmarshalJSON(b []byte) error
- func (id ID) Value() (driver.Value, error)
- type InstanceID
- type Iterator
- type Node
- type ParseError
- type RandomID
- type Set
Constants ¶
const Production = "prod"
Production is the internal name for production ksuid, but is omitted during marshaling.
Variables ¶
This section is empty.
Functions ¶
func SetEnvironment ¶
func SetEnvironment(environment string)
SetEnvironment overrides the default environment name in the exported node. This will effect all invocations of the exported Generate function.
func SetInstanceID ¶
func SetInstanceID(instanceID InstanceID)
SetInstanceID overrides the default instance id in the exported node. This will effect all invocations of the Generate function.
Types ¶
type DockerID ¶
type DockerID struct {
ContainerID []byte
}
DockerID identifies a Node by its Docker container ID.
func NewDockerID ¶
NewDockerID returns a DockerID for the current Docker container.
func ParseDockerID ¶
ParseDockerID unmarshals a DockerID from a sequence of bytes.
type HardwareID ¶
type HardwareID struct {
MachineID net.HardwareAddr
ProcessID uint16
}
HardwareID identifies a Node using its Mac Address and Process ID.
func NewHardwareID ¶
func NewHardwareID() (*HardwareID, error)
NewHardwareID returns a HardwareID for the current node.
func ParseHardwareID ¶
func ParseHardwareID(b []byte) (*HardwareID, error)
ParseHardwareID unmarshals a HardwareID from a sequence of bytes.
func (*HardwareID) Bytes ¶
func (hid *HardwareID) Bytes() [8]byte
func (*HardwareID) Scheme ¶
func (hid *HardwareID) Scheme() byte
type ID ¶
type ID struct {
Environment string
Resource string
Timestamp time.Time
InstanceID InstanceID
SequenceID uint32
}
ID is an optionally prefixed, k-sortable globally unique ID.
func (ID) MarshalJSON ¶
MarshalJSON implements a custom JSON string marshaler.
func (*ID) Scan ¶
Scan implements a custom database/sql.Scanner to support unmarshaling from standard database drivers.
func (*ID) UnmarshalJSON ¶
UnmarshalJSON implements a custom JSON string unmarshaler.
type InstanceID ¶
type InstanceID interface {
// Scheme returns the single byte used to identify the InstanceID.
Scheme() byte
// Bytes returns the serialized form of the InstanceID.
Bytes() [8]byte
}
InstanceID is an interface implemented to identify a instance for a node in a unique manor.
func ParseInstanceID ¶
func ParseInstanceID(b []byte) (InstanceID, error)
ParseInstanceID unmarshals a prefixed node ID into its dedicated type.
type Iterator ¶
type Iterator struct {
// contains filtered or unexported fields
}
Iterator goes over every item currently in the set in a thread-safe way.
type Node ¶
type Node struct {
Environment string
InstanceID InstanceID
// contains filtered or unexported fields
}
Node contains metadata used for ksuid generation for a specific machine.
func NewNode ¶
func NewNode(environment string, instanceID InstanceID) *Node
NewNode returns a ID generator for the current machine.
type ParseError ¶
type ParseError struct {
// contains filtered or unexported fields
}
ParseError is returned when unexpected input is encountered when parsing user input to an ID.
func (ParseError) Error ¶
func (pe ParseError) Error() string
type RandomID ¶
type RandomID struct {
Random [8]byte
}
RandomID identifies a Node by a random sequence of bytes.
func NewRandomID ¶
NewRandomID returns a RandomID initialized by a PRNG.
func ParseRandomID ¶
ParseRandomID unmarshals a RandomID from a sequence of bytes.
type Set ¶
type Set struct {
// contains filtered or unexported fields
}
Set is a thread-safe, ordered array of KSUID where each item exists exactly once.
All Read/Write operations are O(1). Deletion is O(n).
func NewSet ¶
NewSet initializes a KSUID set for unique sets of KSUID, optionally based on an initial array of KSUID.
func (*Set) Append ¶
Append inserts the given ID to the end of the set, if it does not already exist. Returns true if item is new to the set.
Complexity: O(1)
Source Files
Directories