instanceid

README

Instance Identification

A golang implementation of Instance-Identification for microservices

This package supports the handling of instance-identification fields as proposed in Theos paper.

In short, via an instance-identification header field, a micro-service instance can disclose its identity by responding with structured information.

This becomes in particular of interest if the micro-service also includes instance-information of other called services in its response.

A single instance is represented through its MIID

MIID := <sN> "/" <vN> ["/" <vA>] "%" <t>s

Example: msA/1.1/feature-branch-2345abcd%222s

The complete call-graph including it's own MIID is represented by:

CIID := MIID [ "(" UIDs+ ")"]
UIDs := CIID [ "+" CIID ]+

This package provides some helpers to work with this type of instance-identification

CIID := MIID [ "(" UIDs+ ")"]
UIDs := CIID [ "+" CIID ]+
MIID := <sN> "/" <vN> ["/" <vA>] "%" <t>s

Supported functionality

This package supports the

• creation
• parsing
• encoding
• human-friendly display
• examples on the usage

of instance-ids

Documentation

Index

• Constants
• func SanityCheck(miid string) bool
• type Ciid
• type IOption
  • func (o IOption) Command() string
• type IRequest
  • func NewIRequestFromString(v string) *IRequest
  • func (r IRequest) GetHeader() string
  • func (r IRequest) GetIidAuth() string
  • func (r IRequest) HasKey() bool
  • func (r IRequest) HasOptions() bool
  • func (r IRequest) Options() Options
  • func (r *IRequest) SetIidAuth(id string) IidRequest
  • func (r *IRequest) SetOption(o Option) IidRequest
  • func (r IRequest) String() string
• type IidRequest
• type Miid
• type Option
• type Options
• type Stack
  • func (s *Stack) IsEmpty() bool
  • func (s *Stack) Pop() (Ciid, bool)
  • func (s *Stack) Push(str Ciid)
• type StdCiid
  • func NewStdCiid(id string) (ciid *StdCiid)
  • func (c StdCiid) Ciids() Stack
  • func (m StdCiid) ClearStack() StdCiid
  • func (c StdCiid) Contains(miid string) bool
  • func (c StdCiid) Miid() Miid
  • func (c *StdCiid) SetCiids(s Stack) Ciid
  • func (ciid *StdCiid) SetEpoch(startTime time.Time) Ciid
  • func (m StdCiid) SetStack(callStack Stack) StdCiid
  • func (c StdCiid) String() string
  • func (c StdCiid) TreePrint() string
• type StdMiid
  • func NewStdMiid(s string) *StdMiid
  • func (m StdMiid) Contains(s string) bool
  • func (m *StdMiid) SetEpoch(startTime time.Time) Miid
  • func (m *StdMiid) SetT(t int) Miid
  • func (m StdMiid) Sn() string
  • func (m *StdMiid) String() string
  • func (m StdMiid) T() int
  • func (m StdMiid) Va() string
  • func (m StdMiid) Vn() string

Examples

• IRequest
• NewIRequestFromString

Constants

const XINSTANCEID = "X-Instance-Id"

Std header-name for HTTP-Requests

Functions

func SanityCheck

func SanityCheck(miid string) bool

SanityCheck checks the given miid against some rules to ensure that it can be an Miid returns true if miid could be an Miid false otherwise

Types

type Ciid

type Ciid interface {

	// Returns the miid part of the ciids
	Miid() Miid

	// Returns the call stack
	Ciids() Stack

	// Returns the canoncical instance id representation
	String() string

	// Sets the epoch to now, with time being startTime of service. Chainable
	SetEpoch(time.Time) Ciid

	// Sets the call stack. Chainable
	SetCiids(Stack) Ciid
}

Defines the capabilities of a CIID

type IOption

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

func (IOption) Command

func (o IOption) Command() string

type IRequest

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

Example

iir := IRequest{}
iir.SetOption(
	IOption{
		commandName: "v",
	},
).SetIidAuth("caffee")
fmt.Println("String: " + iir.String())
fmt.Println("IdAuth: " + iir.GetIidAuth())

Output:

String: key=caffee options=v
IdAuth: caffee

func NewIRequestFromString

func NewIRequestFromString(v string) *IRequest

NewIRequestFromString creates a new IRequest from a value header passed as string

Example

// Create a new Request object with no auth key and some options
iir := NewIRequestFromString("empty options=cv")

fmt.Println("String: " + iir.String())
fmt.Println("IdAuth: " + iir.GetIidAuth())
fmt.Println("Header: " + iir.GetHeader())

Output:

String: empty options=cv
IdAuth: empty
Header: X-Instance-Id: empty options=cv

func (IRequest) GetHeader

func (r IRequest) GetHeader() string

GetHeader returns the canonical iid-request Header string represenation

func (IRequest) GetIidAuth

func (r IRequest) GetIidAuth() string

GetIidAuth returns the authorisation key value, or an empty string if not set.

func (IRequest) HasKey

func (r IRequest) HasKey() bool

HasKey returns true, if a key element was present. False if empty, or no keys at all

func (IRequest) HasOptions

func (r IRequest) HasOptions() bool

HasOptions returns true, in case options have been indicated, false otherwise

func (IRequest) Options

func (r IRequest) Options() Options

Options returns the options set

func (*IRequest) SetIidAuth

func (r *IRequest) SetIidAuth(id string) IidRequest

SetIidAuth set's the authorisation key value. Chainable Value xyz is included literally as key=xyz If empty string is passed no authorisation key will be send

func (*IRequest) SetOption

func (r *IRequest) SetOption(o Option) IidRequest

SetOption sets an option for the Iid-Request header. Chainable

func (IRequest) String

func (r IRequest) String() string

String returns the canonical iid-request value string represenation

type IidRequest

type IidRequest interface {

	// SetIidAuth set's the authorisation key value. Chainable
	// Value xyz is included literally as key=xyz
	// If empty string is passed no authorisation key will be send
	SetIidAuth(string) IidRequest

	// GetIidAuth returns the authorisation key value, or an empty string if not set.
	GetIidAuth() string

	// Options returns the options set
	Options() Options

	// HasOptions returns true, in case options have been indicated, false otherwise
	HasOptions() bool

	// HasKey returns true, if a key element was present. False if empty, or no keys at all
	HasKey() bool

	// SetOption sets an option for the Iid-Request header. Chainable
	SetOption(Option) IidRequest

	// String returns the canonical iid-request value string represenation
	String() string

	// GetHeader returns the canonical iid-request Header string represenation
	GetHeader() string
}

type Miid

type Miid interface {
	// Returns the service name
	Sn() string

	// Retunrs the version number
	Vn() string

	// Returns the application specific part of the miid
	Va() string

	// Returns the epoch of the miid
	T() int

	// Returns the canoncical instance id representation
	String() string

	// Sets the epoch of the miid in s. Chainable
	SetT(int) Miid

	// Sets the epoch to now, with time being startTime of service. Chainable
	SetEpoch(time.Time) Miid
}

Defines the capabilities of a MIID

type Option

type Option interface {
	Command() string
}

An IID-Request Option

type Options

type Options map[string]Option

A collection of IID-Request options

type Stack

type Stack []Ciid

Stack represents a list of services that have been called by the Ciid

func (*Stack) IsEmpty

func (s *Stack) IsEmpty() bool

IsEmpty: check if stack is empty

func (*Stack) Pop

func (s *Stack) Pop() (Ciid, bool)

Remove and return top element of stack. Return false if stack is empty.

func (*Stack) Push

func (s *Stack) Push(str Ciid)

Push a new value onto the stack

type StdCiid

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

func NewStdCiid

func NewStdCiid(id string) (ciid *StdCiid)

NewCiid creates a new Ciid from a string in the form of Sn1/Vn1/Va1%t1s(Sn2/Vn2/Va2%t2s+Sn3/Vn3/Va3%t3s(Sn4/Vn4/Va4%t4s))

func (StdCiid) Ciids

func (c StdCiid) Ciids() Stack

func (StdCiid) ClearStack

func (m StdCiid) ClearStack() StdCiid

func (StdCiid) Contains

func (c StdCiid) Contains(miid string) bool

Contains returns true if the Ciid contains the left aligned miid as part of the call graph

func (StdCiid) Miid

func (c StdCiid) Miid() Miid

func (*StdCiid) SetCiids

func (c *StdCiid) SetCiids(s Stack) Ciid

func (*StdCiid) SetEpoch

func (ciid *StdCiid) SetEpoch(startTime time.Time) Ciid

SetEpoch sets the epoch field based on a given StartTime. Chainable.

func (StdCiid) SetStack

func (m StdCiid) SetStack(callStack Stack) StdCiid

func (StdCiid) String

func (c StdCiid) String() string

String returns the textual representation of the Ciid

func (StdCiid) TreePrint

func (c StdCiid) TreePrint() string

TreePrint prints a tree representation of the complete call-graph of a Ciid

type StdMiid

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

func NewStdMiid

func NewStdMiid(s string) *StdMiid

func (StdMiid) Contains

func (m StdMiid) Contains(s string) bool

Contains returns true if s is contained left aligned, else or if s is empty return false

func (*StdMiid) SetEpoch

func (m *StdMiid) SetEpoch(startTime time.Time) Miid

SetEpoch sets the epoch field based on a given StartTime. Chainable.

func (*StdMiid) SetT

func (m *StdMiid) SetT(t int) Miid

func (StdMiid) Sn

func (m StdMiid) Sn() string

func (*StdMiid) String

func (m *StdMiid) String() string

String returns the textual representation of the Miid

func (StdMiid) T

func (m StdMiid) T() int

func (StdMiid) Va

func (m StdMiid) Va() string

func (StdMiid) Vn

func (m StdMiid) Vn() string