routing

Documentation

Index

• type HostIndex
• type ID
  • func (id ID) Bytes() []byte
  • func (id ID) Loggable() map[string]any
  • func (id ID) MarshalText() ([]byte, error)
  • func (id ID) String() string
  • func (id *ID) UnmarshalText(b []byte) error
• type Index
• type Iterator
• type Meta
  • func (m Meta) At(i int) (MetaField, error)
  • func (m Meta) Get(key string) (string, error)
  • func (m Meta) Index() (indexes [][]byte, err error)
  • func (m Meta) Len() int
  • func (m Meta) String() string
• type MetaField
  • func ParseField(s string) (MetaField, error)
  • func (f MetaField) String() (s string)
• type MetaIndex
• type PeerIndex
• type Record
• type ServerIndex
• type Snapshot
• type Table
  • func New(t0 time.Time) Table
  • func (table Table) Advance(t time.Time)
  • func (table Table) Snapshot() Snapshot
  • func (table Table) Upsert(rec Record) bool

Types

type HostIndex

type HostIndex interface {
	HostBytes() ([]byte, error)
}

HostIndex is an optional interface for Index that designates the "id" index in the routing table. The Record type MAY also implement HostIndex to provide fast, allocation-free indexing of hostnames.

type ID

type ID uint64

ID is an opaque identifier that identifies a unique host instance on the network. A fresh ID is generated for each cluster.Router instance, making it possible to distinguish between multiple runs of a libp2p host with a fixed peer identity.

IDs are not guaranteed to be globally unique.

func (ID) Bytes

func (id ID) Bytes() []byte

func (ID) Loggable

func (id ID) Loggable() map[string]any

func (ID) MarshalText

func (id ID) MarshalText() ([]byte, error)

func (ID) String

func (id ID) String() string

func (*ID) UnmarshalText

func (id *ID) UnmarshalText(b []byte) error

type Index

type Index interface {
	// String returns the index name.
	String() string

	// Prefix returns true if the index is a prefix match
	Prefix() bool
}

Index is a pointer to a 'column' in the routing table's schema. Indexes MUST implement index methods corresponding to the index name returned by String(). See schema.go for more information.

type Iterator

type Iterator interface {
	// Next pops a record from the head of the stream and
	// returns it to the caller. Subsequent calls to Next
	// will return a different record. When the stream is
	// exhausted, Next returns nil.
	Next() Record
}

Iterator is a stateful object that enumerates routing records. Iterator's methods are NOT guaranteed to be thread-safe, but implementations MUST permit multiple iterators to operate concurently.

Implementations MAY operate on immutable snapshots of routing-table state, so callers SHOULD consume record streams promptly.

type Meta

type Meta capnp.TextList

Meta is an indexed set of key-value pairs describing arbitrary metadata.

func (Meta) At

func (m Meta) At(i int) (MetaField, error)

At returns the metadata field at index i.

func (Meta) Get

func (m Meta) Get(key string) (string, error)

Get returns the value associated with the supplied key. If the key is not found, Get returns ("", nil). Errors are reserved for failures in reading or parsing fields.

func (Meta) Index

func (m Meta) Index() (indexes [][]byte, err error)

Index returns a set of indexes for the metadata fields.

func (Meta) Len

func (m Meta) Len() int

Len returns the number of metadata fields present in the set.

func (Meta) String

func (m Meta) String() string

type MetaField

type MetaField struct {
	Key, Value string
}

MetaField is a key-value pair.

func ParseField

func ParseField(s string) (MetaField, error)

func (MetaField) String

func (f MetaField) String() (s string)

type MetaIndex

type MetaIndex interface {
	MetaBytes() ([]byte, error)
}

MetaIndex is an optional interface for Index that designates a single key-value pair. Note that Record does NOT support this interface, since the Meta type already provides its own indexing method.

type PeerIndex

type PeerIndex interface {
	PeerBytes() ([]byte, error)
}

PeerIndex is an optional interface for Index that designates the "id" index in the routing table. The Record type MAY also implement PeerIndex to provide fast, allocation-free indexing of peer IDs.

type Record

type Record interface {
	Server() ID
	Peer() peer.ID
	Seq() uint64
	TTL() time.Duration
	Host() (string, error)
	Meta() (Meta, error)
}

Record is an entry in the routing table.

type ServerIndex

type ServerIndex interface {
	ServerBytes() ([]byte, error)
}

ServerIndex is an optional interface for Index that designates the "server" index in the routing table. The Record type MAY also implement ServerIndex to provide allocation-free indexing.

type Snapshot

type Snapshot interface {
	Get(Index) (Iterator, error)
	GetReverse(Index) (Iterator, error)
	LowerBound(Index) (Iterator, error)
	ReverseLowerBound(Index) (Iterator, error)
}

Snapshot provides iteration strategies over an isolated snapshot of the routing-table. Implementations MUST NOT mutate the state of the routing table, and MUST support concurrent iteration.

type Table

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

func New

func New(t0 time.Time) Table

func (Table) Advance

func (table Table) Advance(t time.Time)

Advance the state of the routing table to the current time. Expired entries will be evicted from the table.

func (Table) Snapshot

func (table Table) Snapshot() Snapshot

func (Table) Upsert

func (table Table) Upsert(rec Record) bool

Upsert inserts a record in the routing table, updating it if it already exists. Returns false if rec is stale.