bloxid

README

BloxID

This package, bloxid, implements typed guids for identifying resource objects globally in the system. Resources are not specific to services/applications but must contain an entity type.

Typed guids have the advantage of being globally unique, easily readable, and strongly typed for authorization and logging. The trailing characters provide sufficient entropy to make each resource universally unique.

bloxid package provides methods for generating and parsing versioned typed guids.

bloxid supports different schemes for the unique id portion of the bloxid

• extrinsic
• hashid
• random

Scheme - extrinsic

create bloxid from extrinsic id

v0, err := NewV0("",
            WithEntityDomain("iam"),
            WithEntityType("user"),
            WithRealm("us-com-1"),
            WithExtrinsic("123456"),
        )
// v0.String(): blox0.iam.user.us-com-1.ivmfiurrgiztinjweaqcaiba
// v0.Decoded(): "123456"

parse bloxid to retrieve extrinsic id

parsed, err := NewV0("blox0.iam.user.us-com-1.ivmfiurrgiztinjweaqcaiba")
// v0.Decoded(): "123456"

Scheme - hashid

create bloxid from hashid

v0, err := NewV0("",
            WithEntityDomain("infra"),
            WithEntityType("host"),
            WithRealm("us-com-1"),
            WithHashIDInt64(1),
            WithHashIDSalt("test"),
        )
// v0.String(): blox0.infra.host.us-com-1.jbeuiwrsmq3tkmzwmuzwcojsmrqwemrtgy3tqzbvhbsdizjvhe2dkn3cgzrdizlb
// v0.HashIDInt64(): 1

parse bloxid to retrieve hashid

parsed, err := NewV0("blox0.infra.host.us-com-1.jbeuiwrsmq3tkmzwmuzwcojsmrqwemrtgy3tqzbvhbsdizjvhe2dkn3cgzrdizlb",
    WithHashIDSalt("test")
)
// v0.HashIDInt64(): 1

Scheme - random

create bloxid from generated random id

v0, err := NewV0("",
            WithEntityDomain("iam"),
            WithEntityType("group"),
            WithRealm("us-com-1"),
        )
// v0.String(): blox0.iam.group.us-com-1.tshwyq3mfkgqqcfa76a5hbr2uaayzw3h
// v0.Decoded(): "9c8f6c436c2a8d0808a0ff81d3863aa0018cdb67"

parse bloxid to retrieve extrinsic id

parsed, err := NewV0("blox0.iam.group.us-com-1.tshwyq3mfkgqqcfa76a5hbr2uaayzw3h")
// v0.Decoded(): "9c8f6c436c2a8d0808a0ff81d3863aa0018cdb67"

Documentation

Overview

Bloxid implements typed guids for identifying resource objects globally in the system. Resources are not specific to services/applications but must contain an entity type.

Typed guids have the advantage of being globally unique, easily readable, and strongly typed for authorization and logging. The trailing characters provide sufficient entropy to make each resource universally unique.

Bloxid package provides methods for generating and parsing versioned typed guids.

Index

• Constants
• Variables
• func WithEntityDomain(domain string) func(o *V0Options)
• func WithEntityType(eType string) func(o *V0Options)
• func WithExtrinsicID(eid string) func(o *V0Options)
• func WithHashIDInt64(id int64) func(o *V0Options)
• func WithHashIDSalt(salt string) func(o *V0Options)
• func WithRealm(realm string) func(o *V0Options)
• type EncodeDecodeOpts
• type GenerateV0Opts
• type ID
• type V0
  • func NewV0(bloxid string, fnOpts ...EncodeDecodeOpts) (*V0, error)
  • func (v *V0) DecodedID() string
  • func (v *V0) Domain() string
  • func (v *V0) EncodedID() string
  • func (v *V0) HashIDInt64() int64
  • func (v *V0) Realm() string
  • func (v *V0) Scheme() string
  • func (v *V0) String() string
  • func (v *V0) Type() string
  • func (v *V0) Version() string
• type V0Options
• type Version
  • func (v Version) String() string

Constants

const (
	DefaultUniqueIDDecodedCharSize = 40                                     // must be even number and multiple of 40 bits
	DefaultUniqueIDEncodedCharSize = DefaultUniqueIDDecodedCharSize * 5 / 8 // must be divisible by 8 without remainder
	DefaultUniqueIDByteSize        = DefaultUniqueIDDecodedCharSize / 2     // must be divisible by 2 without remainder
	DefaultEntropySize             = DefaultUniqueIDDecodedCharSize         // deprecated but kept for back compat
)

const (
	UniqueIDEncodedMinCharSize = 16

	VersionUnknown Version = iota
	Version0       Version = iota

	IDSchemeRandom = "random"
)

const (
	IDSchemeExtrinsic = "extrinsic"
)

const (
	IDSchemeHashID = "hashid"
)

const (
	V0Delimiter = "."
)

Variables

var (
	ErrEmptyExtrinsicID   = errors.New("empty extrinsic id")
	ErrInvalidExtrinsicID = errors.New("invalid extrinsic id")
)

var (
	ErrInvalidSalt = errors.New("invalid salt")
	ErrInvalidID   = errors.New("invalid id")
)

var (
	ErrInvalidVersion      error = errors.New("invalid bloxid version")
	ErrInvalidEntityDomain error = errors.New("entity domain must be non-empty")
	ErrInvalidEntityType   error = errors.New("entity type must be non-empty")
	ErrInvalidUniqueIDLen  error = errors.New("unique ID did not meet minimum length requirements")

	ErrIDEmpty error = errors.New("empty bloxid")
	ErrV0Parts error = errors.New("invalid number of parts found")
)

Functions

func WithEntityDomain

func WithEntityDomain(domain string) func(o *V0Options)

func WithEntityType

func WithEntityType(eType string) func(o *V0Options)

func WithExtrinsicID

func WithExtrinsicID(eid string) func(o *V0Options)

WithExtrinsicID supplies a locally unique ID that is not randomly generated

func WithHashIDInt64

func WithHashIDInt64(id int64) func(o *V0Options)

func WithHashIDSalt

func WithHashIDSalt(salt string) func(o *V0Options)

func WithRealm

func WithRealm(realm string) func(o *V0Options)

Types

type EncodeDecodeOpts

type EncodeDecodeOpts func(o *V0Options)

type GenerateV0Opts

type GenerateV0Opts func(o *V0Options)

type ID

type ID interface {
	// String returns the complete resource ID
	String() string
	// Version returns a serialized representation of the ID version
	// ie. `V0`
	Version() string // V0
	// Domain returns entity domain ie. `infra`
	Domain() string
	// Type returns entity type ie. `host`
	Type() string
	// Realm is optional and returns the cloud realm that
	// the resource is found in ie. `us-com-1`, `eu-com-1`, ...
	Realm() string
	// EncodedID returns the unique id in encoded format
	EncodedID() string
	// DecodedID returns the unique id in decoded format
	DecodedID() string
	// Return the id scheme
	Scheme() string
}

ID implements the interface for parsing a resource identifier

type V0

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

V0 represents a typed guid

func NewV0

func NewV0(bloxid string, fnOpts ...EncodeDecodeOpts) (*V0, error)

NewV0 parse a string into a typed guid, return an error if the string fails validation.

func (*V0) DecodedID

func (v *V0) DecodedID() string

DecodedID implements ID.decoded

func (*V0) Domain

func (v *V0) Domain() string

Domain implements ID.domain

func (*V0) EncodedID

func (v *V0) EncodedID() string

EncodedID implements ID.encoded

func (*V0) HashIDInt64

func (v *V0) HashIDInt64() int64

HashIDInt64 implements ID.hashIDInt64

func (*V0) Realm

func (v *V0) Realm() string

Realm implements ID.realm

func (*V0) Scheme

func (v *V0) Scheme() string

Scheme of the id

func (*V0) String

func (v *V0) String() string

Serialize the typed guid as a string

func (*V0) Type

func (v *V0) Type() string

Type implements ID.entityType

func (*V0) Version

func (v *V0) Version() string

Version of the string

type V0Options

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

V0Options required options to create a typed guid

type Version

type Version uint8

func (Version) String

func (v Version) String() string