api

module
v0.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 26, 2023 License: Apache-2.0

README

Protocol Documentation

Table of Contents

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)

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL