peers

Documentation

Overview

Package peers contains an interface for managing nodes in the mesh.

Index

• Constants
• Variables
• func IsValidID(id string) bool
• func NewGraphStore(st storage.Storage) graph.Store[string, Node]
• type Edge
• type Graph
  • func NewGraph(st storage.Storage) Graph
• type GraphStore
  • func (g *GraphStore) AddEdge(sourceNode, targetNode string, edge graph.Edge[string]) error
  • func (g *GraphStore) AddVertex(nodeID string, node Node, props graph.VertexProperties) error
  • func (g *GraphStore) Edge(sourceNode, targetNode string) (graph.Edge[string], error)
  • func (g *GraphStore) ListEdges() ([]graph.Edge[string], error)
  • func (g *GraphStore) ListVertices() ([]string, error)
  • func (g *GraphStore) RemoveEdge(sourceNode, targetNode string) error
  • func (g *GraphStore) RemoveVertex(nodeID string) error
  • func (g *GraphStore) UpdateEdge(sourceNode, targetNode string, edge graph.Edge[string]) error
  • func (g *GraphStore) Vertex(nodeID string) (node Node, props graph.VertexProperties, err error)
  • func (g *GraphStore) VertexCount() (int, error)
• type Node
  • func (n Node) MarshalJSON() ([]byte, error)
  • func (n *Node) Proto(status v1.ClusterStatus) *v1.MeshNode
  • func (n *Node) UnmarshalJSON(b []byte) error
• type Peers
  • func New(db storage.Storage) Peers
• type PutLeaseOptions
• type PutOptions

Constants

const EdgesPrefix = "/registry/edges"

EdgesPrefix is where edges are stored in the database. edges are indexed by their source and target node IDs in the format /registry/edges/<source>/<target>.

const NodesPrefix = "/registry/nodes"

NodesPrefix is where nodes are stored in the database. nodes are indexed by their ID in the format /registry/nodes/<id>.

Variables

var ErrEdgeNotFound = graph.ErrEdgeNotFound

ErrEdgeNotFound is returned when an edge is not found.

var ErrNodeNotFound = errors.New("node not found")

ErrNodeNotFound is returned when a node is not found.

var InvalidNodeIDChars = []rune{'/', '\\', ':', '*', '?', '"', '\'', '<', '>', '|', ','}

InvalidNodeIDChars are the characters that are not allowed in node IDs.

Functions

func IsValidID

func IsValidID(id string) bool

IsValidID returns true if the given node ID is valid.

func NewGraphStore

func NewGraphStore(st storage.Storage) graph.Store[string, Node]

NewGraphStore creates a new GraphStore instance.

Types

type Edge

type Edge struct {
	// From is the ID of the source node.
	From string `json:"from"`
	// To is the ID of the target node.
	To string `json:"to"`
	// Weight is the weight of the edge.
	Weight int `json:"weight"`
	// Attrs are the edge's attributes.
	Attrs map[string]string `json:"attrs"`
}

Edge represents an edge between two nodes.

type Graph

type Graph graph.Graph[string, Node]

Graph is the graph.Graph implementation for the mesh network.

func NewGraph

func NewGraph(st storage.Storage) Graph

NewGraph creates a new Graph instance.

type GraphStore

type GraphStore struct {
	storage.Storage
}

GraphStore implements graph.Store[string, Node] where string is the node ID and Node is the node itself.

func (*GraphStore) AddEdge

func (g *GraphStore) AddEdge(sourceNode, targetNode string, edge graph.Edge[string]) error

AddEdge should add an edge between the vertices with the given source and target hashes.

If either vertex doesn't exit, ErrVertexNotFound should be returned for the respective vertex. If the edge already exists, ErrEdgeAlreadyExists should be returned.

func (*GraphStore) AddVertex

func (g *GraphStore) AddVertex(nodeID string, node Node, props graph.VertexProperties) error

AddVertex should add the given vertex with the given hash value and vertex properties to the graph. If the vertex already exists, it is up to you whether ErrVertexAlreadyExists or no error should be returned.

func (*GraphStore) Edge

func (g *GraphStore) Edge(sourceNode, targetNode string) (graph.Edge[string], error)

Edge should return the edge joining the vertices with the given hash values. It should exclusively look for an edge between the source and the target vertex, not vice versa. The graph implementation does this for undirected graphs itself.

Note that unlike Graph.Edge, this function is supposed to return an Edge[K], i.e. an edge that only contains the vertex hashes instead of the vertices themselves.

If the edge doesn't exist, ErrEdgeNotFound should be returned.

func (*GraphStore) ListEdges

func (g *GraphStore) ListEdges() ([]graph.Edge[string], error)

ListEdges should return all edges in the graph in a slice.

func (*GraphStore) ListVertices

func (g *GraphStore) ListVertices() ([]string, error)

ListVertices should return all vertices in the graph in a slice.

func (*GraphStore) RemoveEdge

func (g *GraphStore) RemoveEdge(sourceNode, targetNode string) error

RemoveEdge should remove the edge between the vertices with the given source and target hashes.

If either vertex doesn't exist, it is up to you whether ErrVertexNotFound or no error should be returned. If the edge doesn't exist, it is up to you whether ErrEdgeNotFound or no error should be returned.

func (*GraphStore) RemoveVertex

func (g *GraphStore) RemoveVertex(nodeID string) error

RemoveVertex should remove the vertex with the given hash value. If the vertex doesn't exist, ErrVertexNotFound should be returned. If the vertex has edges to other vertices, ErrVertexHasEdges should be returned.

func (*GraphStore) UpdateEdge

func (g *GraphStore) UpdateEdge(sourceNode, targetNode string, edge graph.Edge[string]) error

UpdateEdge should update the edge between the given vertices with the data of the given Edge instance. If the edge doesn't exist, ErrEdgeNotFound should be returned.

func (*GraphStore) Vertex

func (g *GraphStore) Vertex(nodeID string) (node Node, props graph.VertexProperties, err error)

Vertex should return the vertex and vertex properties with the given hash value. If the vertex doesn't exist, ErrVertexNotFound should be returned.

func (*GraphStore) VertexCount

func (g *GraphStore) VertexCount() (int, error)

VertexCount should return the number of vertices in the graph. This should be equal to the length of the slice returned by ListVertices.

type Node

type Node struct {
	// ID is the node's ID.
	ID string `json:"id"`
	// PublicKey is the node's public key.
	PublicKey wgtypes.Key `json:"publicKey"`
	// PrimaryEndpoint is the primary public endpoint of the node.
	PrimaryEndpoint string `json:"primaryEndpoint"`
	// WireGuardEndpoints are the available wireguard endpoints of the node.
	WireGuardEndpoints []string `json:"wireGuardEndpoints"`
	// ZoneAwarenessID is the node's zone awareness ID.
	ZoneAwarenessID string `json:"zoneAwarenessId"`
	// PrivateIPv4 is the node's private IPv4 address.
	PrivateIPv4 netip.Prefix `json:"privateIpv4"`
	// PrivateIPv6 is the node's IPv6 network.
	PrivateIPv6 netip.Prefix `json:"privateIpv6"`
	// GRPCPort is the node's GRPC port.
	GRPCPort int `json:"grpcPort"`
	// RaftPort is the node's Raft port.
	RaftPort int `json:"raftPort"`
	// CreatedAt is the time the node was created.
	CreatedAt time.Time `json:"createdAt"`
	// UpdatedAt is the time the node was last updated.
	UpdatedAt time.Time `json:"updatedAt"`
}

Node represents a node. Not all fields are populated in all contexts. A fully populated node is returned by Get and List.

func (Node) MarshalJSON

func (n Node) MarshalJSON() ([]byte, error)

MarshalJSON marshals a Node to JSON.

func (*Node) Proto

func (n *Node) Proto(status v1.ClusterStatus) *v1.MeshNode

Proto converts a Node to the protobuf representation.

func (*Node) UnmarshalJSON

func (n *Node) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals a Node from JSON.

type Peers

type Peers interface {
	// Graph returns the graph of nodes.
	Graph() Graph
	// Put creates or updates a node.
	Put(ctx context.Context, opts *PutOptions) (Node, error)
	// PutLease creates or updates a node lease.
	PutLease(ctx context.Context, opts *PutLeaseOptions) error
	// Get gets a node by ID.
	Get(ctx context.Context, id string) (Node, error)
	// Delete deletes a node.
	Delete(ctx context.Context, id string) error
	// List lists all nodes.
	List(ctx context.Context) ([]Node, error)
	// ListIDs lists all node IDs.
	ListIDs(ctx context.Context) ([]string, error)
	// ListPublicNodes lists all public nodes.
	ListPublicNodes(ctx context.Context) ([]Node, error)
	// ListByZoneID lists all nodes in a zone.
	ListByZoneID(ctx context.Context, zoneID string) ([]Node, error)
	// AddEdge adds an edge between two nodes.
	PutEdge(ctx context.Context, edge Edge) error
	// RemoveEdge removes an edge between two nodes.
	RemoveEdge(ctx context.Context, from, to string) error
	// DrawGraph draws the graph of nodes to the given Writer.
	DrawGraph(ctx context.Context, w io.Writer) error
}

Peers is the peers interface.

func New

func New(db storage.Storage) Peers

New returns a new Peers interface.

type PutLeaseOptions

type PutLeaseOptions struct {
	// ID is the node's ID.
	ID string
	// IPv4 is the node's IPv4 address.
	IPv4 netip.Prefix
	// IPv6 is the node's IPv6 network.
	IPv6 netip.Prefix
}

PutLeaseOptions are options for creating or updating a node lease.

type PutOptions

type PutOptions struct {
	// ID is the node's ID.
	ID string
	// PublicKey is the node's public key.
	PublicKey wgtypes.Key
	// PrimaryEndpoint is the primary public endpoint of the node.
	PrimaryEndpoint string
	// WireGuardEndpoints are the available wireguard endpoints of the node.
	WireGuardEndpoints []string
	// ZoneAwarenessID is the node's zone awareness ID.
	ZoneAwarenessID string
	// GRPCPort is the node's GRPC port.
	GRPCPort int
	// RaftPort is the node's Raft port.
	RaftPort int
}

PutOptions are options for creating or updating a node.