storage

Documentation

Overview

Package storage defines the interfaces for the storage provider.

Index

• Constants
• Variables
• func ExpandACL(ctx context.Context, rbac RBAC, acl types.NetworkACL) error
• func ExpandACLs(ctx context.Context, rbac RBAC, acls types.NetworkACLs) error
• func IsSystemGroup(name string) bool
• func IsSystemRole(name string) bool
• func IsSystemRoleBinding(name string) bool
• func NewGraphWithStore(store GraphStore) types.PeerGraph
• type BootstrapOptions
• type BootstrapResults
  • func Bootstrap(ctx context.Context, db MeshDB, opts BootstrapOptions) (results BootstrapResults, err error)
• type Consensus
• type ConsensusStorage
• type DualStorage
• type GraphStore
• type KVSubscribeFunc
• type MeshDB
• type MeshDataStore
• type MeshState
• type MeshStorage
• type Networking
• type PeerFilter
  • func FilterAgainstNode(nodeID types.NodeID) PeerFilter
  • func FilterByFeature(feature v1.Feature) PeerFilter
  • func FilterByIPv4Prefix(prefix netip.Prefix) PeerFilter
  • func FilterByIPv6Prefix(prefix netip.Prefix) PeerFilter
  • func FilterByIsPublic() PeerFilter
  • func FilterByZoneID(zoneID string) PeerFilter
• type PeerFilters
  • func (f PeerFilters) Filter(nodes []types.MeshNode) []types.MeshNode
  • func (f PeerFilters) Match(node types.MeshNode) bool
• type PeerSubscribeFunc
• type Peers
• type PrefixIterator
• type Provider
• type RBAC

Constants

const (
	// DefaultMeshDomain is the default domain for the mesh network.
	DefaultMeshDomain = "webmesh.internal"
	// DefaultIPv4Network is the default IPv4 network for the mesh.
	DefaultIPv4Network = "172.16.0.0/12"
	// DefaultNetworkPolicy is the default network policy for the mesh.
	DefaultNetworkPolicy = "accept"
	// DefaultBootstrapListenAddress is the default listen address for the bootstrap transport.
	DefaultBootstrapListenAddress = "[::]:9001"
	// DefaultBootstrapAdvertiseAddress is the default advertise address for the bootstrap transport.
	DefaultBootstrapAdvertiseAddress = "127.0.0.1:9001"
	// DefaultBootstrapPort is the default port for the bootstrap transport.
	DefaultBootstrapPort = 9001
	// DefaultMeshAdmin is the default mesh admin node ID.
	DefaultMeshAdmin = "admin"
)

Variables

var (
	// BootstrapNodesNetworkACLName is the name of the bootstrap nodes NetworkACL.
	BootstrapNodesNetworkACLName = []byte("bootstrap-nodes")
	// NetworkACLsPrefix is where NetworkACLs are stored in the database.
	NetworkACLsPrefix = types.RegistryPrefix.For([]byte("network-acls"))
	// RoutesPrefix is where Routes are stored in the database.
	RoutesPrefix = types.RegistryPrefix.For([]byte("routes"))
)

var (
	// MeshAdminRole is the name of the mesh admin role.
	MeshAdminRole = []byte("mesh-admin")
	// MeshAdminRoleBinding is the name of the mesh admin rolebinding.
	MeshAdminRoleBinding = []byte("mesh-admin")
	// VotersRole is the name of the voters role.
	VotersRole = []byte("voters")
	// VotersGroup is the name of the voters group.
	VotersGroup = []byte("voters")
	// BootstrapVotersRoleBinding is the name of the bootstrap voters rolebinding.
	BootstrapVotersRoleBinding = []byte("bootstrap-voters")
)

var EdgesPrefix = types.RegistryPrefix.ForString("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>.

var ErrStopIteration = fmt.Errorf("stop iteration")

ErrStopIteration is a special error that can be returned by PrefixIterator to stop iteration.

var NodesPrefix = types.RegistryPrefix.ForString("nodes")

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

Functions

func ExpandACL

func ExpandACL(ctx context.Context, rbac RBAC, acl types.NetworkACL) error

ExpandACL will use the given RBAC interface to expand any group references in the ACL.

func ExpandACLs

func ExpandACLs(ctx context.Context, rbac RBAC, acls types.NetworkACLs) error

ExpandACLs will use the given RBAC interface to expand any group references in the ACLs.

func IsSystemGroup

func IsSystemGroup(name string) bool

IsSystemGroup returns true if the group is a system group.

func IsSystemRole

func IsSystemRole(name string) bool

IsSystemRole returns true if the role is a system role.

func IsSystemRoleBinding

func IsSystemRoleBinding(name string) bool

IsSystemRoleBinding returns true if the rolebinding is a system rolebinding.

func NewGraphWithStore

func NewGraphWithStore(store GraphStore) types.PeerGraph

NewGraphWithStore creates a new Graph instance with the given graph storage implementation.

Types

type BootstrapOptions

type BootstrapOptions struct {
	// MeshDomain is the mesh domain.
	MeshDomain string
	// IPv4Network is the IPv4 prefix.
	IPv4Network string
	// IPv6Network is the IPv6 prefix. If left unset,
	// one will be generated.
	IPv6Network string
	// Admin is the admin node ID.
	Admin string
	// DefaultNetworkPolicy is the default network policy.
	DefaultNetworkPolicy string
	// BootstrapNodes are the bootstrap nodes to use.
	BootstrapNodes []string
	// Voters are additional voting nodes to add to the voters group.
	Voters []string
	// DisableRBAC disables RBAC.
	DisableRBAC bool
}

BootstrapOptions are options for bootstrapping the database.

type BootstrapResults

type BootstrapResults struct {
	// NetworkV4 is the IPv4 network.
	NetworkV4 netip.Prefix
	// NetworkV6 is the IPv6 network.
	NetworkV6 netip.Prefix
	// MeshDomain is the mesh domain.
	MeshDomain string
}

BoostrapResults are the results of bootstrapping the database.

func Bootstrap

func Bootstrap(ctx context.Context, db MeshDB, opts BootstrapOptions) (results BootstrapResults, err error)

Bootstrap attempts to bootstrap the given database. If data already exists, ErrAlreadyBootstrapped will be returned, but with results populated with the existing data.

type Consensus

type Consensus interface {
	// IsLeader returns true if the node is the leader of the storage group.
	IsLeader() bool
	// IsMember returns true if the node is a member of the storage group.
	IsMember() bool
	// StepDown should be called to relinquish leadership of the storage group.
	StepDown(context.Context) error
	// GetPeer returns the peer with the given ID.
	GetPeer(context.Context, string) (*v1.StoragePeer, error)
	// GetPeers returns the peers of the storage group.
	GetPeers(context.Context) ([]*v1.StoragePeer, error)
	// GetLeader returns the leader of the storage group.
	GetLeader(context.Context) (*v1.StoragePeer, error)
	// AddVoter adds a voter to the consensus group.
	AddVoter(context.Context, *v1.StoragePeer) error
	// AddObserver adds an observer to the consensus group.
	AddObserver(context.Context, *v1.StoragePeer) error
	// DemoteVoter demotes a voter to an observer.
	DemoteVoter(context.Context, *v1.StoragePeer) error
	// RemovePeer removes a peer from the consensus group. If wait
	// is true, the function will wait for the peer to be removed.
	RemovePeer(ctx context.Context, peer *v1.StoragePeer, wait bool) error
}

Consensus is the interface for managing storage consensus.

type ConsensusStorage

type ConsensusStorage interface {
	io.Closer
	raft.LogStore
	raft.StableStore

	// Snapshot returns a snapshot of the storage.
	Snapshot(ctx context.Context) (io.Reader, error)
	// Restore restores a snapshot of the storage.
	Restore(ctx context.Context, r io.Reader) error
}

ConsensusStorage is the interface for storing and retrieving data about the state of consensus. This is currently only used by the built-in raftstorage implementation.

type DualStorage

type DualStorage interface {
	MeshStorage
	ConsensusStorage
}

DualStorage represents a storage interface that can serve as both mesh and consensus storage.

type GraphStore

type GraphStore interface {
	// PeerGraphStore is a storage interface for peer graph data.
	types.PeerGraphStore

	// Subscribe subscribes to changes to nodes and edges.
	Subscribe(ctx context.Context, fn PeerSubscribeFunc) (context.CancelFunc, error)
}

GraphStore is a storage interface for graph data.

type KVSubscribeFunc

type KVSubscribeFunc func(key, value []byte)

KVSubscribeFunc is the function signature for subscribing to changes to a key.

type MeshDB

type MeshDB interface {
	// MeshDataStore is the underlying MeshDataStore instance.
	MeshDataStore
	// Peers returns a simplified interface for managing nodes in the mesh
	// via the underlying MeshDataStore.
	Peers() Peers
}

MeshDB is the interface for the mesh database. It provides access to all storage interfaces.

type MeshDataStore

type MeshDataStore interface {
	// GraphStore returns the interface for managing network topology and data
	// about peers.
	GraphStore() GraphStore
	// RBAC returns the interface for managing RBAC policies in the mesh.
	RBAC() RBAC
	// MeshState returns the interface for querying mesh state.
	MeshState() MeshState
	// Networking returns the interface for managing networking in the mesh.
	Networking() Networking
}

MeshDataStore is an interface for storing and retrieving data about the state of the mesh. It can be implemented by external providers to be wrapped into a MeshDB for use throughout the library.

type MeshState

type MeshState interface {
	// GetIPv6Prefix returns the IPv6 prefix.
	GetIPv6Prefix(ctx context.Context) (netip.Prefix, error)
	// SetIPv6Prefix sets the IPv6 prefix.
	SetIPv6Prefix(ctx context.Context, prefix netip.Prefix) error
	// GetIPv4Prefix returns the IPv4 prefix.
	GetIPv4Prefix(ctx context.Context) (netip.Prefix, error)
	// SetIPv4Prefix sets the IPv4 prefix.
	SetIPv4Prefix(ctx context.Context, prefix netip.Prefix) error
	// GetMeshDomain returns the mesh domain.
	GetMeshDomain(ctx context.Context) (string, error)
	// SetMeshDomain sets the mesh domain.
	SetMeshDomain(ctx context.Context, domain string) error
	// GetMeshState returns the full mesh state.
	GetMeshState(ctx context.Context) (types.NetworkState, error)
}

MeshState is the interface for querying mesh state.

type MeshStorage

type MeshStorage interface {
	// Close should close the underlying storage as well as any other resources
	// that the provider may have allocated. This should be called automatically
	// by the provider.
	io.Closer

	// GetValue returns the value of a key.
	GetValue(ctx context.Context, key []byte) ([]byte, error)
	// PutValue sets the value of a key. TTL is optional and can be set to 0.
	PutValue(ctx context.Context, key, value []byte, ttl time.Duration) error
	// Delete removes a key.
	Delete(ctx context.Context, key []byte) error
	// ListKeys returns all keys with a given prefix.
	ListKeys(ctx context.Context, prefix []byte) ([][]byte, error)
	// IterPrefix iterates over all keys with a given prefix. It is important
	// that the iterator not attempt any write operations as this will cause
	// a deadlock. The iteration will stop if the iterator returns an error.
	IterPrefix(ctx context.Context, prefix []byte, fn PrefixIterator) error
	// Subscribe will call the given function whenever a key with the given prefix is changed.
	// The returned function can be called to unsubscribe.
	Subscribe(ctx context.Context, prefix []byte, fn KVSubscribeFunc) (context.CancelFunc, error)
}

MeshStorage is the interface for storing and retrieving data about the state of the mesh.

type Networking

type Networking interface {
	// PutNetworkACL creates or updates a NetworkACL.
	PutNetworkACL(ctx context.Context, acl types.NetworkACL) error
	// GetNetworkACL returns a NetworkACL by name.
	GetNetworkACL(ctx context.Context, name string) (types.NetworkACL, error)
	// DeleteNetworkACL deletes a NetworkACL by name.
	DeleteNetworkACL(ctx context.Context, name string) error
	// ListNetworkACLs returns a list of NetworkACLs.
	ListNetworkACLs(ctx context.Context) (types.NetworkACLs, error)
	// PutRoute creates or updates a Route.
	PutRoute(ctx context.Context, route types.Route) error
	// GetRoute returns a Route by name.
	GetRoute(ctx context.Context, name string) (types.Route, error)
	// GetRoutesByNode returns a list of Routes for a given Node.
	GetRoutesByNode(ctx context.Context, nodeID types.NodeID) (types.Routes, error)
	// GetRoutesByCIDR returns a list of Routes for a given CIDR.
	GetRoutesByCIDR(ctx context.Context, cidr netip.Prefix) (types.Routes, error)
	// DeleteRoute deletes a Route by name.
	DeleteRoute(ctx context.Context, name string) error
	// ListRoutes returns a list of Routes.
	ListRoutes(ctx context.Context) (types.Routes, error)
}

Networking is the interface to the database models for network resources.

type PeerFilter

type PeerFilter func(types.MeshNode) bool

PeerFilter is a filter for nodes.

func FilterAgainstNode

func FilterAgainstNode(nodeID types.NodeID) PeerFilter

FilterAgainstNode returns a new filter that matches nodes that are not a given node ID.

func FilterByFeature

func FilterByFeature(feature v1.Feature) PeerFilter

FilterByFeature returns a new filter that matches nodes with a given feature.

func FilterByIPv4Prefix

func FilterByIPv4Prefix(prefix netip.Prefix) PeerFilter

FilterByIPv4Prefix returns a new filter that matches nodes whose private IPv4 address is in a given prefix.

func FilterByIPv6Prefix

func FilterByIPv6Prefix(prefix netip.Prefix) PeerFilter

FilterByIPv6Prefix returns a new filter that matches nodes whose private IPv6 address is in a given prefix.

func FilterByIsPublic

func FilterByIsPublic() PeerFilter

FilterByIsPublic returns a new filter that matches public nodes.

func FilterByZoneID

func FilterByZoneID(zoneID string) PeerFilter

FilterByZoneID returns a new filter that matches nodes in a given zone.

type PeerFilters

type PeerFilters []PeerFilter

PeerFilters is a list of filters.

func (PeerFilters) Filter

func (f PeerFilters) Filter(nodes []types.MeshNode) []types.MeshNode

Filter filters a list of nodes.

func (PeerFilters) Match

func (f PeerFilters) Match(node types.MeshNode) bool

Match returns true if the node matches all filters.

type PeerSubscribeFunc

type PeerSubscribeFunc func([]types.MeshNode)

PeerSubscribeFunc is a function that can be used to subscribe to peer changes. The function is called with multiple peers when the change reflects a new edge being added or removed. The function is called with a single peer when the change reflects a node being added or removed.

type Peers

type Peers interface {
	// Graph should return the underlying graph instance.
	Graph() types.PeerGraph
	// Put creates or updates a node.
	Put(ctx context.Context, n types.MeshNode) error
	// Get gets a node by ID.
	Get(ctx context.Context, id types.NodeID) (types.MeshNode, error)
	// GetByPubKey gets a node by their public key.
	GetByPubKey(ctx context.Context, key crypto.PublicKey) (types.MeshNode, error)
	// Delete deletes a node.
	Delete(ctx context.Context, id types.NodeID) error
	// List lists all nodes.
	List(ctx context.Context, filters ...PeerFilter) ([]types.MeshNode, error)
	// ListIDs lists all node IDs.
	ListIDs(ctx context.Context) ([]types.NodeID, error)
	// Subscribe subscribes to node changes.
	Subscribe(ctx context.Context, fn PeerSubscribeFunc) (context.CancelFunc, error)
	// AddEdge adds an edge between two nodes.
	PutEdge(ctx context.Context, edge types.MeshEdge) error
	// GetEdge gets an edge between two nodes.
	GetEdge(ctx context.Context, from, to types.NodeID) (types.MeshEdge, error)
	// RemoveEdge removes an edge between two nodes.
	RemoveEdge(ctx context.Context, from, to types.NodeID) error
}

Peers is the peers interface.

type PrefixIterator

type PrefixIterator func(key, value []byte) error

PrefixIterator is the function signature for iterating over all keys with a given prefix.

type Provider

type Provider interface {
	// Close should close the underlying storage as well as any other resources
	// that the provider may have allocated.
	io.Closer
	// Start should start the provider and any resources that it may need.
	Start(context.Context) error
	// Bootstrap should bootstrap the provider for first-time usage.
	Bootstrap(context.Context) error
	// Status returns the status of the storage provider. It should never error.
	// If inaccurate status is available, the node should return itself as a peer
	// with a message describing the inaccuracy.
	Status() *v1.StorageStatus
	// ListenPort should return the TCP port that the storage provider is listening on.
	ListenPort() uint16
	// MeshDB returns the underlying MeshDB instance. The provider does not
	// need to guarantee consistency on read operations.
	MeshDB() MeshDB
	// Consensus returns the underlying Consensus instance for managing voting/observing
	// nodes and leader election.
	Consensus() Consensus
	// MeshStorage returns the underlying raw MeshStorage instance. The provider does
	// not need to guarantee consistency on read operations. This should only be used
	// for arbitrary key/value storage that has not been abstracted behind the MeshDB.
	MeshStorage() MeshStorage
}

Provider is a provider of MeshStorage.

type RBAC

type RBAC interface {
	// SetEnabled sets the RBAC enabled state.
	SetEnabled(ctx context.Context, enabled bool) error
	// GetEnabled returns the RBAC enabled state.
	GetEnabled(ctx context.Context) (bool, error)

	// PutRole creates or updates a role.
	PutRole(ctx context.Context, role types.Role) error
	// GetRole returns a role by name.
	GetRole(ctx context.Context, name string) (types.Role, error)
	// DeleteRole deletes a role by name.
	DeleteRole(ctx context.Context, name string) error
	// ListRoles returns a list of all roles.
	ListRoles(ctx context.Context) (types.RolesList, error)

	// PutRoleBinding creates or updates a rolebinding.
	PutRoleBinding(ctx context.Context, rolebinding types.RoleBinding) error
	// GetRoleBinding returns a rolebinding by name.
	GetRoleBinding(ctx context.Context, name string) (types.RoleBinding, error)
	// DeleteRoleBinding deletes a rolebinding by name.
	DeleteRoleBinding(ctx context.Context, name string) error
	// ListRoleBindings returns a list of all rolebindings.
	ListRoleBindings(ctx context.Context) ([]types.RoleBinding, error)

	// PutGroup creates or updates a group.
	PutGroup(ctx context.Context, group types.Group) error
	// GetGroup returns a group by name.
	GetGroup(ctx context.Context, name string) (types.Group, error)
	// DeleteGroup deletes a group by name.
	DeleteGroup(ctx context.Context, name string) error
	// ListGroups returns a list of all groups.
	ListGroups(ctx context.Context) ([]types.Group, error)

	// ListNodeRoles returns a list of all roles for a node.
	ListNodeRoles(ctx context.Context, nodeID types.NodeID) (types.RolesList, error)
	// ListUserRoles returns a list of all roles for a user.
	ListUserRoles(ctx context.Context, user types.NodeID) (types.RolesList, error)
}

RBAC is the interface to the database models for RBAC.