ident

Documentation

Overview

Package ident contains types that represent various Rinq identifiers.

Index

• func MustValidate(v validatable)
• type MessageID
  • func ParseMessageID(str string) (id MessageID, err error)
  • func (id MessageID) ShortString() string
  • func (id MessageID) String() string
  • func (id MessageID) Validate() error
• type PeerID
  • func NewPeerID() PeerID
  • func (id PeerID) Session(seq uint32) SessionID
  • func (id PeerID) ShortString() string
  • func (id PeerID) String() string
  • func (id PeerID) Validate() error
• type Ref
  • func (ref Ref) After(r Ref) bool
  • func (ref Ref) Before(r Ref) bool
  • func (ref Ref) Message(seq uint32) MessageID
  • func (ref Ref) ShortString() string
  • func (ref Ref) String() string
  • func (ref Ref) Validate() error
• type Revision
• type SessionID
  • func ParseSessionID(str string) (id SessionID, err error)
  • func (id SessionID) At(rev Revision) Ref
  • func (id SessionID) ShortString() string
  • func (id SessionID) String() string
  • func (id SessionID) Validate() error

Functions

func MustValidate

func MustValidate(v validatable)

MustValidate panics if v.Validate() returns an error.

Types

type MessageID

type MessageID struct {
	Ref Ref
	Seq uint32
}

MessageID uniquely identifies a message that originated from a session.

func ParseMessageID

func ParseMessageID(str string) (id MessageID, err error)

ParseMessageID parses a string representation of a message ID.

func (MessageID) ShortString

func (id MessageID) ShortString() string

ShortString returns a string representation based on the session's short string representation.

func (MessageID) String

func (id MessageID) String() string

func (MessageID) Validate

func (id MessageID) Validate() error

Validate returns nil if the ID is valid.

type PeerID

type PeerID struct {
	// Clock is a time-based portion of the ID, this helps uniquely identify
	// peer IDs over longer time-scales, such as when looking back through
	// logs, etc.
	Clock uint64

	// Rand is a unique number identifying this peer within a network at any
	// given time. It is generated randomly and then reserved when the peer
	// connects to the network.
	Rand uint16
}

PeerID uniquely identifies a peer within a network.

Peer IDs contain a clock component and a random 16-bit integer component. They are rendered in hexadecimal encoding, with a hypen separating the two components, such as "58AEE146-191C".

For a given network, the random component is guaranteed to be unique at any given time; and, assuming a stable system clock it is highly likely that the ID is unique across time. This makes peer IDs useful for tracking peer behavior in logs.

All other IDs generated by a peer, such as SessionID and MessageID are derived from the peer ID.

func NewPeerID

func NewPeerID() PeerID

NewPeerID creates a new ID struct. There is no guarantee that the ID is unique until the peer is connected to a network.

func (PeerID) Session

func (id PeerID) Session(seq uint32) SessionID

Session returns a new session ID for this peer with seq as the sequence number.

func (PeerID) ShortString

func (id PeerID) ShortString() string

ShortString returns a string representation of the peer ID without the clock component (e.g. "191C").

func (PeerID) String

func (id PeerID) String() string

String returns a string representation including both the Clock and Rand components (e.g. "58AEE146-191C").

func (PeerID) Validate

func (id PeerID) Validate() error

Validate returns an error if the peer ID is not valid.

Neither the Clock nor Rand component may be zero.

type Ref

type Ref struct {
	ID  SessionID
	Rev Revision
}

Ref refers to a session at a specific revision.

func (Ref) After

func (ref Ref) After(r Ref) bool

After returns true if this ref's revision is after r.

func (Ref) Before

func (ref Ref) Before(r Ref) bool

Before returns true if this ref's revision is before r.

func (Ref) Message

func (ref Ref) Message(seq uint32) MessageID

Message returns a new message ID derived from this ref with seq as the sequence number.

func (Ref) ShortString

func (ref Ref) ShortString() string

ShortString returns a string representation based on the session's short string representation.

func (Ref) String

func (ref Ref) String() string

func (Ref) Validate

func (ref Ref) Validate() error

Validate returns nil if the Ref is valid.

type Revision

type Revision uint32

Revision holds the "version" of a session. A session's revision is incremented when a change is made to its attribute table. A session that has never been modified, and hence has no attributes always has a revision of 0.

type SessionID

type SessionID struct {
	// Peer is the ID of the peer that owns the session.
	Peer PeerID

	// Seq is a monotonically increasing sequence allocated to each session in
	// the order it is created by the owning peer. Application sessions begin
	// with a sequence value of 1. The sequnce value zero is reserved for the
	// "zero-session", which is used for internal operations.
	Seq uint32
}

SessionID uniquely identifies a session within a network.

Session IDs contain a peer component, and a 32-bit sequence component. They are rendereds as a peer ID, followed by a period, then the sequence component as a decimal, such as "58AEE146-191C.45".

Because the peer ID is embedded, the same uniqueness guarantees apply to the session ID as to the peer ID.

func ParseSessionID

func ParseSessionID(str string) (id SessionID, err error)

ParseSessionID parses a string representation of a session ID.

func (SessionID) At

func (id SessionID) At(rev Revision) Ref

At returns a Ref for this session ID.

func (SessionID) ShortString

func (id SessionID) ShortString() string

ShortString returns a string representation of the session ID based on the peer IDs short representation (e.g. "191C.45").

func (SessionID) String

func (id SessionID) String() string

String returns a string representation of the session ID based on the full peer ID (e.g. "58AEE146-191C.45").

func (SessionID) Validate

func (id SessionID) Validate() error

Validate returns an error if the session ID is not valid.

The session ID is valid if the embedded peer ID is valid.