api

README

Protocol Documentation

Table of Contents

• v1/admin_messages.proto
  • MDeleteRaftACLRequest
  • MGetRaftACLRequest
  • MRaftACL
  • MRaftACLList
  • EACLAction
• v1/admin.proto
  • SAdmin
• v1/mesh_messages.proto
  • MGetNodeRequest
  • MMeshNode
  • MNodeList
  • EClusterStatus
  • EFeature
• v1/mesh.proto
  • SMesh
• v1/node_messages.proto
  • MDataChannelNegotiation
  • MGetStatusRequest
  • MJoinRequest
  • MJoinResponse
  • MLeaveRequest
  • MStatus
  • MWireguardPeer
  • EDataChannel
• v1/node.proto
  • SNode
• v1/node_metrics.proto
  • MCPUTimes
  • MDiskInfo
  • MHostInfo
  • MHostMetrics
  • MLoadAverage
  • MMemoryInfo
  • MNodeMetrics
  • MOSInfo
  • MPeerMetrics
• v1/node_raft.proto
  • MRaftApplyResponse
  • MRaftLogEntry
  • MSQLExec
  • MSQLExecResult
  • MSQLParameter
  • MSQLQuery
  • MSQLQueryResult
  • MSQLStatement
  • MSQLValues
  • ERaftCommandType
  • ESQLParameterType
• v1/peer_discovery.proto
  • MListRaftPeersResponse
  • MRaftPeer
  • SPeerDiscovery
• v1/webrtc_messages.proto
  • MDataChannelOffer
  • MStartDataChannelRequest
• v1/webrtc.proto
  • SWebRTC
• Scalar Value Types

v1/admin_messages.proto

Top

DeleteRaftACLRequest

DeleteRaftACLRequest is a request to delete a RaftACL.

Field	Type	Label	Description
name	string		name is the name of the ACL.

GetRaftACLRequest

GetRaftACLRequest is a request to get a RaftACL.

Field	Type	Label	Description
name	string		name is the name of the ACL.

RaftACL

RaftACL is an ACL that applies to Raft nodes.

Field	Type	Label	Description
name	string		name is the name of the ACL.
patterns	string	repeated	patterns is a list of node patterns this ACL applies to.
action	ACLAction		action is the action of this ACL. For RaftACLs This is if the matching nodes are allowed to vote in elections or not.

RaftACLList

RaftACLList is a list of RaftACLs.

Field	Type	Label	Description
items	RaftACL	repeated	items is a list of RaftACLs.

ACLAction

ACLAction is the action of an ACL.

Name	Number	Description
DENY	0	DENY denies the action.
ALLOW	1	ALLOW allows the action.

v1/admin.proto

Top

Admin

Admin is the service that provides cluster admin operations. Most methods

require the leader to be contacted.

Method Name	Request Type	Response Type	Description
PutRaftACL	.RaftACL	.google.protobuf.Empty	PutRaftACL creates or updates an ACL.
DeleteRaftACL	.DeleteRaftACLRequest	.google.protobuf.Empty	DeleteRaftACL deletes an ACL by name.
GetRaftACL	.GetRaftACLRequest	.RaftACL	GetRaftACL returns an ACL by name.
ListRaftACLs	.google.protobuf.Empty	.RaftACLList	ListRaftACLs returns the ACLs for the Raft cluster.

v1/mesh_messages.proto

Top

GetNodeRequest

GetNodeRequest is a request to get a node.

Field	Type	Label	Description
id	string		id is the ID of the node.

MeshNode

MeshNode is a node that has been registered with the controller.

Field	Type	Label	Description
id	string		id is the ID of the node.
primary_endpoint	string		primary_endpoint is the primary_endpoint of the node.
endpoints	string	repeated	endpoints are alternate endpoints for the node.
raft_port	int32		raft_port is the Raft listen port of the node.
grpc_port	int32		grpc_port is the gRPC listen port of the node.
wireguard_port	int32		wireguard_port is the Wireguard listen port of the node.
public_key	string		public_key is the public key of the node.
private_ipv4	string		private_ipv4 is the private IPv4 address of the node.
private_ipv6	string		private_ipv6 is the private IPv6 address of the node.
updated_at	google.protobuf.Timestamp		updated_at is the last time the node joined the cluster.
created_at	google.protobuf.Timestamp		created_at is the creation time for the node.
cluster_status	ClusterStatus		cluster_status is the status of the node in the cluster.

NodeList

NodeList is a list of nodes.

Field	Type	Label	Description
nodes	MeshNode	repeated	nodes is the list of nodes.

ClusterStatus

ClusterStatus is the status of the node in the cluster.

Name	Number	Description
CLUSTER_STATUS_UNKNOWN	0	CLUSTER_STATUS_UNKNOWN is the default status.
CLUSTER_LEADER	1	CLUSTER_LEADER is the status for the leader node.
CLUSTER_VOTER	2	CLUSTER_VOTER is the status for a voter node.
CLUSTER_NON_VOTER	3	CLUSTER_NON_VOTER is the status for a non-voter node.

Feature

Feature is a list of features supported by a node.

Name	Number	Description
FEATURE_NONE	0	FEATURE_NONE is the default feature set.
NODES	1	NODES is the feature for nodes. This is always supported.
LEADER_PROXY	2	LEADER_PROXY is the feature for leader proxying.
MESH_API	3	MESH_API is the feature for the mesh API.
PEER_DISCOVERY	4	PEER_DISCOVERY is the feature for peer discovery.
METRICS	5	METRICS is the feature for exposing metrics.
ICE_NEGOTIATION	6	ICE_NEGOTIATION is the feature for ICE negotiation.
TURN_SERVER	7	TURN_SERVER is the feature for TURN server.
MESH_DNS	8	MESH_DNS is the feature for mesh DNS.

v1/mesh.proto

Top

Mesh

Mesh is a service that can optionally be exposed by a node. It provides methods for

interfacing with the webmesh from the outside. Some methods are only available on the

leader. Nodes can enable the leader proxy to expose the leader's Mesh service.

Method Name	Request Type	Response Type	Description
GetNode	GetNodeRequest	MeshNode	GetNode gets a node by ID.
ListNodes	.google.protobuf.Empty	NodeList	ListNodes lists all nodes.

v1/node_messages.proto

Top

DataChannelNegotiation

DataChannelNegotiation is the message for communicating data channels to nodes.

Field	Type	Label	Description
proto	string		proto is the protocol of the traffic.
src	string		src is the address of the client that initiated the request.
dst	string		dst is the destination address of the traffic.
port	uint32		port is the destination port of the traffic.
offer	string		offer is the offer for the node to use as its local description.
answer	string		answer is the answer for the node to use as its remote description.
candidate	string		candidate is an ICE candidate.
stun_servers	string	repeated	stun_servers is the list of STUN servers to use.

GetStatusRequest

GetStatusRequest is a request to get the status of a node.

Field	Type	Label	Description
id	string		id is the ID of the node. If unset, the status of the local node is returned.

JoinRequest

JoinRequest is a request to join the cluster.

Field	Type	Label	Description
id	string		id is the ID of the node.
public_key	string		public_key is the public wireguard key of the node to broadcast to peers.
raft_port	int32		raft_port is the Raft listen port of the node.
grpc_port	int32		grpc_port is the gRPC listen port of the node.
wireguard_port	int32		wireguard_port is the Wireguard listen port of the node.
primary_endpoint	string		primary_endpoint is a routable address for the node. If left unset, the node is assumed to be behind a NAT and not directly accessible.
endpoints	string	repeated	endpoints are additional endpoints routable to the node. See primary_endpoint.
assign_ipv4	bool		assign_ipv4 is whether an IPv4 address should be assigned to the node.
prefer_raft_ipv6	bool		prefer_raft_ipv6 is whether IPv6 should be preferred over IPv4 for raft communication. This is only used if assign_ipv4 is true.
as_voter	bool		as_voter is whether the node should receive a vote in elections.

JoinResponse

JoinResponse is a response to a join request.

Field	Type	Label	Description
address_ipv4	string		address_ipv4 is the private IPv4 wireguard address of the node in CIDR format representing the network. This is only set if assign_ipv4 was set in the request or no network_ipv6 was provided.
network_ipv6	string		network_ipv6 is the IPv6 network assigned to the node.
peers	WireguardPeer	repeated	peers is a list of wireguard peers to connect to.

LeaveRequest

LeaveRequest is a request to leave the cluster.

Field	Type	Label	Description
id	string		id is the ID of the node.

Status

Status represents the status of a node.

Field	Type	Label	Description
id	string		id is the ID of the node.
version	string		version is the version of the node.
commit	string		commit is the commit of the node.
build_date	string		build_date is the build date of the node.
uptime	string		uptime is the uptime of the node.
started_at	google.protobuf.Timestamp		started_at is the time the node started.
features	Feature	repeated	features is the list of features currently enabled.
wireguard_peers	uint32		wireguard_peers is the number of wireguard peers connected.
cluster_status	ClusterStatus		cluster_status is the status of the node in the cluster.
current_leader	string		current_leader is the current leader of the cluster.

WireguardPeer

WireguardPeer is a peer in the Wireguard network.

Field	Type	Label	Description
id	string		id is the ID of the peer.
public_key	string		public_key is the public key of the peer.
primary_endpoint	string		primary_endpoint is the primary endpoint of the peer, if applicable.
endpoints	string	repeated	endpoints are alternative endpoints of the peer, if applicable.
address_ipv4	string		address_ipv4 is the private IPv4 wireguard address of the peer.
address_ipv6	string		address_ipv6 is the private IPv6 wireguard address of the peer.

DataChannel

DataChannel are the data channels used when communicating over ICE

with a node.

Name	Number	Description
CHANNELS	0	CHANNELS is the data channel used for negotiating new channels. This is the first channel that is opened. The ID of the channel should be 0.
CONNECTIONS	1	CONNECTIONS is the data channel used for negotiating new connections. This is a channel that is opened for each incoming connection from a client. The ID should start at 0 and be incremented for each new connection.

v1/node.proto

Top

Node

Node is the service exposed on every node in the mesh to communicate network

information amongst themselves. Some methods are only available on the currently

elected leader. This service can optionally be exposed on public interfaces to allow

external users to query the mesh state, join as an observer, or proxy/inspect traffic.

Nodes can optionally be configured to proxy requests to the leader. To prefer the leader

handle the request when a non-leader can otherwise serve it, use the "prefer-leader" header.

Method Name	Request Type	Response Type	Description
Join	JoinRequest	JoinResponse	Join is used to join a node to the mesh. The joining node will be added to the mesh as an observer, and will be able to query the mesh state, but will not be able to vote in elections. To join as a voter pass the as_voter flag.
Leave	LeaveRequest	.google.protobuf.Empty	Leave is used to remove a node from the mesh. The node will be removed from the mesh and will no longer be able to query the mesh state or vote in elections.
GetStatus	GetStatusRequest	Status	GetStatus gets the status of a node in the cluster.
NegotiateDataChannel	DataChannelNegotiation stream	DataChannelNegotiation stream	NegotiateDataChannel is used to negotiate a WebRTC connection between a webmesh client and a node in the cluster. The handling server will send the target node the source address, the destination for traffic, and STUN/TURN servers to use for the negotiation. The node responds with an offer to be forwarded to the client. When the handler receives an answer from the client, it forwards it to the node. Once the node receives the answer, the stream can optionally be used to exchange ICE candidates.

v1/node_metrics.proto

Top

CPUTimes

CPUTimes is the CPU times.

Field	Type	Label	Description
load_average	LoadAverage
user	string		user is the user CPU time.
system	string		system is the system CPU time.
idle	string		idle is the idle CPU time.
io_wait	string		io_wait is the IO wait CPU time.
irq	string		irq is the IRQ CPU time.
nice	string		nice is the nice CPU time.
soft_irq	string		soft_irq is the soft IRQ CPU time.
steal	string		steal is the steal CPU time.

DiskInfo

DiskInfo is the disk information.

Field	Type	Label	Description
filesystem_path	string		filesystem_path is the path the disk is mounted to.
device	string		device is the device of the disk.
total	uint64		total is the total disk space.
free	uint64		free is the free disk space.
used	uint64		used is the used disk space.
used_percent	float		used_percent is the used disk space percentage.
inodes_total	uint64		inodes_total is the total inodes.
inodes_free	uint64		inodes_free is the free inodes.
inodes_used	uint64		inodes_used is the used inodes.
inodes_used_percent	float		inodes_used_percent is the used inodes percentage.

HostInfo

HostInfo is the host information.

Field	Type	Label	Description
architecture	string		architecture is the architecture of the host.
boot_time	string		boot_time is the boot time of the host.
containerized	bool		containerized is whether the host is containerized.
hostname	string		hostname is the hostname of the host.
ips	string	repeated	ips is the list of IP addresses of the host.
kernel_version	string		kernel_version is the kernel version of the host.
macs	string	repeated	macs is the list of MAC addresses of the host.
os	OSInfo		os is the OS of the host.
timezone	string		timezone is the timezone of the host.
uptime	string		uptime is the uptime of the host.

HostMetrics

HostMetrics is the metrics for the host.

Field	Type	Label	Description
host	HostInfo		host is the host metrics.
cpu	CPUTimes		cpu is the CPU metrics.
memory	MemoryInfo		memory is the memory metrics.
disks	DiskInfo	repeated	disks is the disk metrics.

LoadAverage

LoadAverage is the load average.

Field	Type	Label	Description
one	float		one is the 1 minute load average.
five	float		five is the 5 minute load average.
fifteen	float		fifteen is the 15 minute load average.

MemoryInfo

MemoryInfo is the memory information.

Field	Type	Label	Description
total	uint64		total is the total memory.
used	uint64		used is the used memory.
available	uint64		available is the available memory.
free	uint64		free is the free memory.
virtual_total	uint64		virtual_total is the total virtual memory.
virtual_used	uint64		virtual_used is the used virtual memory.
virtual_free	uint64		virtual_free is the free virtual memory.

NodeMetrics

NodeMetrics is the metrics for the node.

Field	Type	Label	Description
device_name	string		device_name is the name of the device.
public_key	string		public_key is the public key of the node.
address_v4	string		address_v4 is the IPv4 address of the node.
address_v6	string		address_v6 is the IPv6 address of the node.
type	string		type is the type of interface being used for wireguard.
listen_port	int32		listen_port is the port wireguard is listening on.
total_receive_bytes	uint64		total_receive_bytes is the total number of bytes received.
total_transmit_bytes	uint64		total_transmit_bytes is the total number of bytes transmitted.
peers	PeerMetrics	repeated	peers are the per-peer statistics.
system	HostMetrics		system is the system metrics for the node.

OSInfo

OSInfo is the OS information.

Field	Type	Label	Description
type	string		type is the type of OS.
family	string		family is the family of OS.
platform	string		platform is the platform of OS.
name	string		name is the name of OS.
version	string		version is the version of OS.
major	int64		major is the major version of OS.
minor	int64		minor is the minor version of OS.
patch	int64		patch is the patch version of OS.
build	string		build is the build version of OS.
codename	string		codename is the codename of OS.

PeerMetrics

PeerMetrics are the metrics for a node's peer.

Field	Type	Label	Description
public_key	string		public_key is the public key of the peer.
endpoint	string		endpoint is the connected endpoint of the peer.
persistent_keep_alive	string		persistent_keep_alive is the persistent keep alive interval for the peer.
last_handshake_time	string		last_handshake_time is the last handshake time for the peer.
allowed_ips	string	repeated	allowed_ips is the list of allowed IPs for the peer.
protocol_version	int64		protocol_version is the version of the wireguard protocol negotiated with the peer.
receive_bytes	uint64		receive_bytes is the bytes received from the peer.
transmit_bytes	uint64		transmit_bytes is the bytes transmitted to the peer.

v1/node_raft.proto

Top

RaftApplyResponse

RaftApplyResponse is the response to an apply request. It

contains the result of applying the log entry.

Field	Type	Label	Description
time	string		time is the total time it took to apply the log entry.
query_result	SQLQueryResult		query is the query result of the log entry.
exec_result	SQLExecResult		exec is the exec result of the log entry.
error	string		error is an error that occurred during the apply.

RaftLogEntry

RaftLogEntry is the data of an entry in the Raft log.

Field	Type	Label	Description
type	RaftCommandType		type is the type of the log entry.
sql_query	SQLQuery		data is the data of the log entry. sql_query is the SQL query of the log entry.
sql_exec	SQLExec		sql_exec is the SQL exec of the log entry.

SQLExec

SQLExec is a SQL exec.

Field	Type	Label	Description
transaction	bool		transaction flags whether the exec is a transaction.
statement	SQLStatement		statement is the statement of the SQL exec.

SQLExecResult

SQLExecResult is the result of a SQL exec.

Field	Type	Label	Description
last_insert_id	int64		last_insert_id is the last insert ID.
rows_affected	int64		rows_affected is the number of rows affected.
error	string		error is an error that occurred during the exec.
time	string		time is the time it took to execute the exec.

SQLParameter

SQLParameter is a parameter of a SQL query.

Field	Type	Label	Description
name	string		name is the name of the parameter.
type	SQLParameterType
int64	sint64
double	double
bool	bool
bytes	bytes
str	string
time	google.protobuf.Timestamp

SQLQuery

SQLQuery is a SQL query.

Field	Type	Label	Description
transaction	bool		transaction flags whether the query is a transaction.
statement	SQLStatement		statement is the statement of the SQL query.

SQLQueryResult

SQLQueryResult contains the rows of a SQL query.

Field	Type	Label	Description
columns	string	repeated	columns is the list of columns.
types	string	repeated	types is the list of types.
values	SQLValues	repeated	values is the list of values.
error	string		error is an error that occurred during the query.
time	string		time is the time it took to execute the query.

SQLStatement

SQLStatement is a SQL statement.

Field	Type	Label	Description
sql	string		sql is the SQL statement.
parameters	SQLParameter	repeated	parameters is the parameters of the SQL statement.

SQLValues

SQLValues is a list of values.

Field	Type	Label	Description
values	SQLParameter	repeated	values is the list of values.

RaftCommandType

RaftCommandType is the type of command being sent to the

Raft log.

Name	Number	Description
UNKNOWN	0	UNKNOWN is the unknown command type.
QUERY	1	QUERY is the query command type.
EXECUTE	2	EXECUTE is the execute command type.

SQLParameterType

Name	Number	Description
SQL_PARAM_UNKNOWN	0	UNKNOWN is the unknown parameter type.
SQL_PARAM_INT64	1	INT64 is the int64 parameter type.
SQL_PARAM_DOUBLE	2	DOUBLE is the double parameter type.
SQL_PARAM_BOOL	3	BOOL is the bool parameter type.
SQL_PARAM_BYTES	4	BYTES is the bytes parameter type.
SQL_PARAM_STRING	5	STRING is the string parameter type.
SQL_PARAM_TIME	6	TIME is the time parameter type.
SQL_PARAM_NULL	7	NULL is the null parameter type.

v1/peer_discovery.proto

Top

ListRaftPeersResponse

ListRaftPeersResponse is the response to ListPeers.

Field	Type	Label	Description
peers	RaftPeer	repeated	Peers is the list of peers.

RaftPeer

RaftPeer is a peer in the Raft cluster.

Field	Type	Label	Description
id	string		ID is the ID of the peer.
address	string		Address is the public gRPC address of the peer.
voter	bool		Voter is whether the peer is a voter.
leader	bool		Leader is whether the peer is the leader.

PeerDiscovery

PeerDiscovery is the service that provides peer discovery. This is a service

that can optionally be exposed by nodes in the mesh to provide peer discovery

to other nodes. Alternative methods of peer discovery can be used, such as

static files or DNS, but running one or more publicly accessible nodes with this

service registered is the simplest method.

It only makes sense to expose this service on a public address on a member of the

Raft cluster. It is not necessary to expose this service on every node in the mesh.

Method Name	Request Type	Response Type	Description
ListPeers	.google.protobuf.Empty	ListRaftPeersResponse	ListPeers returns a list of public peers currently known to the mesh.

v1/webrtc_messages.proto

Top

DataChannelOffer

DataChannelOffer is an offer for a data channel. Candidates

are sent after the offer is sent.

Field	Type	Label	Description
offer	string		offer is the offer.
stun_servers	string	repeated	stun_servers is the list of STUN servers to use.
candidate	string		candidate is an ICE candidate.

StartDataChannelRequest

StartDataChannelRequest is a request to start a data channel.

The answer and candidate fields are populated after the offer

is received.

Field	Type	Label	Description
node_id	string		node_id is the ID of the node to send the data to.
proto	string		proto is the protocol of the traffic.
dst	string		dst is the destination address of the traffic.
port	uint32		port is the destination port of the traffic.
answer	string		answer is the answer to the offer.
candidate	string		candidate is an ICE candidate.

v1/webrtc.proto

Top

WebRTC

WebRTC is a service for negotiating WebRTC connections to nodes in the mesh.

It is typically run alongside a TURN server, however the server can be configured

to use public STUN servers instead.

Method Name	Request Type	Response Type	Description
StartDataChannel	StartDataChannelRequest stream	DataChannelOffer stream	StartDataChannel requests a new WebRTC connection to a node. The client speaks first with the request containing the node ID and where forwarded packets should be sent. The server responds with an offer and STUN servers to be used to establish a WebRTC connection. The client should then respond with an answer to the offer that matches the spec of the DataChannel.CHANNELS enum value. After the offer is accepted, the stream can be used to exchange ICE candidates to speed up the connection process.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)