ids

README

Semantic ID

Overview

This library provides support for creating semantically meaningful identifiers for use in SOA environment.

Semantically meaningful identifiers (further referred simply as 'semantic IDs) allow encoded representation of internal IDs used within the service to be translated to and from opaque string IDs that conceal the nature of internal identifiers and thus allow flexibility of internal implementation (e.g. change from internal ID to external and vice versa).

Also semantic IDs allow easier debugging, i.e. when referred from system logs, developers can easily understand what service/entity particular ID refers to.

Representation

Semantic ID includes 3 parts:

• Encoded service name and version, e.g. 'foo1'
• Optional, encoded entity name, e.g. 'user'
• Encoded ID, e.g. 'q6b60'

Examples of such IDs: foo1-user-q6b60, req-9j35zf3.

Notes:

• ID are case insensitive, i.e. semantic ID a-b-1cd should always be equivalent to A-B-1CD and vice versa.
• Encoded ID prefixes that are used to construct an instance of codec are always required when decoding an ID. E.g. foo1-qw1 is a valid semantic ID (with service name foo and version 1), qw1 is not.
  • Note, that ID may be created without any prefixes, in this case only ID body is required for decoding

Documentation

Index

• Constants
• Variables
• func GetPrefix(maybeSemanticID string) string
• type IDCodec
  • func NewCodecForNames(names ...string) IDCodec

Constants

const MaxBytesIDSize = 256

MaxBytesIDSize defines upper bound limit for number of bytes in a given semantic ID

Variables

var (
	// ErrIDTooBig happens when given ID is too big to be encoded as semantic ID
	// see also MaxBytesIDSize that defines this limit
	ErrIDTooBig = errors.New("value is too big to be encoded into semantic ID")

	// ErrIDEmpty happens when empty ID is asked to be decoded
	ErrIDEmpty = errors.New("can't encode empty value to semantic ID")

	// ErrInvalidChar happens when invalid character is found in a given semantic ID
	ErrInvalidChar = errors.New("given semantic ID contains invalid character")

	// ErrMalformedID happens when given semantic ID is malformed
	ErrMalformedID = errors.New("invalid semantic ID")
)

Functions

func GetPrefix

func GetPrefix(maybeSemanticID string) string

GetPrefix returns prefix which is a part of a given semantic ID

Types

type IDCodec

type IDCodec interface {
	CanDecode(id string) bool

	Encode(value []byte) (string, error)

	Decode(id string) ([]byte, error)

	GetPrefix() string
}

IDCodec defines an interface that abstracts out operations on the semantic IDs

func NewCodecForNames

func NewCodecForNames(names ...string) IDCodec

NewCodecForNames creates IDCodec for a given sequence of names