oid

README

oid

import "github.com/henderjon/oid"

Based on:

• chilts/sid
• oklog/ulid
• https://blog.kowalczyk.info/article/JyRZ/generating-good-unique-ids-in-go.html

Documentation

Overview

package oid provides the ability to generate Un/Ordered Identifiers. These are also most likely very unique. At the very least, they are unique enough.

simplicity > ∞

OIDs are ordered, UIDs are not and the use of math/rand means these are not cryptographically secure.

If there is a desire for greater flexibility use a Generator which allows the customization of the final encoding (base32, base64, hex, etc. (see encoders.go)) and the entropy source and length (math/rand, crypto/rand, etc).

By default, an OID is the base 32 encoding of a binary encoded string comprising an 8 byte nanosecond precision unix timestamp and an 8 byte random number, in that order. The timestamp prefix allows these IDs to be ordered.

If (by any chance) OID is called in the same nanosecond, the random number is incremented instead of a new one being generated. This makes sure that two consecutive IDs generated in the same goroutine are different and ordered.

By default a UID is the base 32 encoding of a binary encoded string comprising two 8 byte random numbers.

Both are safe for concurrent use as they provide their own locking. OID will run out of nanoseconds on Fri, 11 Apr 2262 23:47:16 UTC

Index

• Variables
• func OID() string
• func UID() string
• type Encoder
  • func (e Encoder) EncodeToString(b []byte) string
• type EncoderToString
• type Generator
  • func DefaultGenerator() *Generator
  • func NewGenerator(enc EncoderToString, src io.Reader, len int) *Generator
  • func (gen *Generator) OID() string
  • func (gen *Generator) SID() string
  • func (gen *Generator) UID() string
• type GeneratorInterface

Variables

var (
	// Crockford32Encoder is a base 32 dictionary from Dougland Crockford
	// (https://www.crockford.com/base32.html)
	Crockford32Encoder = base32.NewEncoding("0123456789abcdefghjkmnpqrstvwxyz").WithPadding(base32.NoPadding)
	// HexEncoder is a typical hex representation of bytes. I'm casting it here
	// to allow for a top level package function to satisfy a proper interface.
	HexEncoder = Encoder(hex.EncodeToString)
)

var (
	// MathSource uses math/rand
	MathSource io.Reader = readerFunc(mrand.Read)
	// CryptoSource uses crypto/rand
	CryptoSource io.Reader = readerFunc(crand.Read)
)

Functions

func OID

func OID() string

OID generates an ordered ID

func UID

func UID() string

UID generates an unordered ID

Types

type Encoder

type Encoder func([]byte) string

Encoder is an adapter akin to http.HandlerFunc

func (Encoder) EncodeToString

func (e Encoder) EncodeToString(b []byte) string

EncodeToString allows any Encoder type to match the EncoderToString interface

type EncoderToString

type EncoderToString interface {
	EncodeToString([]byte) string
}

EncoderToString is an interface for encoding bytes to strings

type Generator

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

Generator is an injectable way of creating UIDs and OIDs.

func DefaultGenerator

func DefaultGenerator() *Generator

DefaultGenerator returns a generator setup to emulate the bare OID/UID funcs. This is useful for injecting the default behavior.

func NewGenerator

func NewGenerator(enc EncoderToString, src io.Reader, len int) *Generator

NewGenerator creates a custom UID/OID generator that reads `len` number of bytes from `src` and uses `enc` to encode it as a string. `src` should have enough bytes to cover double the `len` as UID reads `len` twice). `len` should be greater than 0.

func (*Generator) OID

func (gen *Generator) OID() string

OID is a configurable and injectable version of `OID()`.

func (*Generator) SID

func (gen *Generator) SID() string

SID is a configurable and injectable version of `UID()` but does not double the number of bytes used. This simply encodes N number of bytes.

func (*Generator) UID

func (gen *Generator) UID() string

UID is a configurable and injectable version of `OID()`. Be mindful that whatever `len` was used, the length of the resulting UID will be double as `len` is used internally twice.

type GeneratorInterface

type GeneratorInterface interface {
	OID() string // generate a random, orderable ID
	UID() string // generate a random, Un-orderable ID
	SID() string // generate a shorter random, Un-orderable ID
}