README
¶
nbid
Name Based globally unique ID generator
NBID can be generate from arbitrary names using cryptographic hash function (SHA256 by default). The binary representation of the NBID is a 16 byte byte array. The string representation is using base32 hex (w/o padding) for space efficiency when stored in that form (26 bytes). The hex variant of base32 is used to retain the sortability (string and binary representation has same order).
NBID doesn't use base64 because case sensitivity and the 2 non alphanum chars may be an issue when transported as a string between various systems. To validate a base32 NBID, expect a 26 chars long, all uppercase sequence of A to V letters and 0 to 9 numbers ([0-9A-V]{26}).
Features
- Easy to use - Simly a 128 bit hash without complexity of UUID.
- Modern hash - Default hash function is SHA256, but you can use any hash with at least 128 bit output.
- Compact - String representation size is only 26 characters.
- Sortable - Binary and string representation has same order (because of base32hex).
- No case sensitivity - Using only uppercase letters and numbers in string representaiton make NBID usable in environments without case sensitive names (DNS host names, FAT filesystem, etc).
Install
This section about CLI tool, for API usage check Documentation.
You can install the pre-compiled binary or use Docker.
Install the pre-compiled binary
Download the pre-compiled binaries from the releases page and copy to the desired location.
Install with Go
If you have Go environment set up, you can build nbid from source by running:
go get github.com/szkiba/nbid/cmd/nbid
Binary would be installed to $GOPATH/bin/nbid.
Running with Docker
You can also use it within a Docker container. To do that, you'll need to execute the following:
docker run szkiba/nbid
Verifying your installation
To verify your installation, use the nbid -v command:
$ nbid -v
nbid/1.0.0 linux/amd64
You should see nbid/VERSION in the output.
Usage
To print usage information, use the nbid --help command:
$ nbid --help
usage: nbid [name]
Generate NBID for name, or random NBID if name is missing.
Example: nbid "The quick brown fox jumps over the lazy dog"
Output: QUKFNCO7QU098QEAJAUB021E9S
-v prints version
TODO
Document, document, document...
Documentation
¶
Overview ¶
Package nbid is a Name Based globally unique ID generator.
NBID is generated from names using cryptographic hash function (SHA256 by default). The binary representation of the NBID is a 16 byte byte array. The string representation is using base32 hex (w/o padding) for space efficiency when stored in that form (26 bytes). The hex variant of base32 is used to retain the sortability (string and binary representation has same order).
NBID doesn't use base64 because case sensitivity and the 2 non alphanum chars may be an issue when transported as a string between various systems. To validate a base32 NBID, expect a 26 chars long, all uppercase sequence of `A` to `V` letters and `0` to `9` numbers (`[0-9A-V]{26}`).
Index ¶
- func Convert(value string) reflect.Value
- type NBID
- func (id NBID) Bytes() []byte
- func (id NBID) Compare(other NBID) int
- func (id NBID) Equal(other NBID) bool
- func (id NBID) IsNil() bool
- func (id NBID) MarshalBinary() ([]byte, error)
- func (id NBID) MarshalJSON() ([]byte, error)
- func (id NBID) MarshalText() (text []byte, err error)
- func (id *NBID) Scan(src interface{}) error
- func (id NBID) String() string
- func (id *NBID) UnmarshalBinary(data []byte) error
- func (id *NBID) UnmarshalJSON(b []byte) error
- func (id *NBID) UnmarshalText(text []byte) error
- func (id NBID) Value() (driver.Value, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type NBID ¶
type NBID [rawLen]byte
NBID represents a Name Based ID. The binary representation of the NBID is a 16 byte byte array. The string representation is using base32 hex (w/o padding).
func FromBytes ¶
FromBytes creates a new NBID from a byte slice. Returns an error if the slice does not have a length of 16. The bytes are copied from the slice.
func New ¶
New returns a new NBID derived from the SHA256 hash of data. The first 16 bytes of the SHA256 hash are used to form the ID. It is the same as calling:
NewHash(sha256.New(), data)
func NewHash ¶
NewHash returns a new NBID derived from the hash of data generated by h. The hash should be at least 16 byte in length. The first 16 bytes of the hash are used to form the ID.
func Parse ¶
Parse decodes s into an NBID or returns an error. The string representation is using base32 hex (w/o padding). Returns an error if the s does not have a length of 16.
func Random ¶
func Random() NBID
Random returns a new random generated NBID. The strength of the IDs is based on the strength of the crypto/rand package.
func (NBID) Compare ¶
Compare returns an integer comparing two NBIDs. It behaves just like `bytes.Compare`.
func (NBID) MarshalBinary ¶
MarshalBinary implements encoding.BinaryMarshaler.
func (NBID) MarshalJSON ¶
MarshalJSON implements encoding/json Marshaler interface.
func (NBID) MarshalText ¶
MarshalText implements encoding/text TextMarshaler interface.
func (*NBID) Scan ¶
Scan implements sql.Scanner so NBIDs can be read from databases transparently. Currently, database types that map to string and []byte are supported.
func (NBID) String ¶
String returns the string form of NBID, a base32 hex (w/o padding). RFC 4648 / 7. Base 32 Encoding with Extended Hex Alphabet https://tools.ietf.org/html/rfc4648#section-7
func (*NBID) UnmarshalBinary ¶
UnmarshalBinary implements encoding.BinaryUnmarshaler.
func (*NBID) UnmarshalJSON ¶
UnmarshalJSON implements encoding/json Unmarshaler interface.
func (*NBID) UnmarshalText ¶
UnmarshalText implements encoding/text TextUnmarshaler interface.
Source Files
Directories