README ¶
Protocol Documentation
Table of Contents
v1/node.proto
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. |
InterfaceMetrics
InterfaceMetrics is the metrics for the WireGuard interface on a 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. | |
num_peers | int32 | num_peers is the number of peers connected to the node. | |
peers | PeerMetrics | repeated | peers are the per-peer statistics. |
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. | |
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. | |
wireguard_endpoints | string | repeated | wireguard_endpoints is a list of WireGuard endpoints for the node. |
zone_awareness_id | string | zone_awareness_id is the zone awareness ID of the node. | |
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. The request will be denied if the node is not allowed to vote. | |
routes | string | repeated | routes is a list of routes to advertise to peers. The request will be denied if the node is not allowed to put routes. |
direct_peers | string | repeated | direct_peers is a list of extra peers that should be connected to directly over ICE. The request will be denied if the node is not allowed to put data channels or edges. The default joining behavior creates non-ICE links between the caller and the joiner. If the caller has a primary endpoint, the joiner will link the caller to all other nodes with a primary endpoint. If the caller has a zone awareness ID, the joiner will link the caller to all other nodes with the same zone awareness ID that also have a primary endpoint. |
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. The bits are set to the network bits of the Mesh IPv4 network. | |
address_ipv6 | string | address_ipv6 is the IPv6 network assigned to the node. | |
network_ipv6 | string | network_ipv6 is the IPv6 network of the Mesh. | |
peers | WireGuardPeer | repeated | peers is a list of wireguard peers to connect to. |
ice_servers | string | repeated | ice_servers is a list of public nodes that can be used to negotiate ICE connections if required. This may only be populated when one of the peers has the ICE flag set. This must be set if the requestor specifies direct_peers. |
LeaveRequest
LeaveRequest is a request to leave the cluster.
Field | Type | Label | Description |
---|---|---|---|
id | string | id is the ID of the node. |
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. |
SnapshotRequest
SnapshotRequest is a request to create a snapshot. It is intentionally
empty for now as there are no options.
SnapshotResponse
SnapshotResponse is a response to a snapshot request.
Field | Type | Label | Description |
---|---|---|---|
snapshot | bytes | snapshot is the snapshot data. |
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. |
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. | |
current_term | uint64 | current_term is the current term of the cluster. | |
last_log_index | uint64 | last_log_index is the last log index of the cluster. | |
last_applied | uint64 | last_applied is the last applied index of the cluster. | |
interface_metrics | InterfaceMetrics | interface_metrics are the metrics for the node's interfaces. |
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. | |
wireguard_endpoints | string | repeated | wireguard_endpoints are the WireGuard endpoints for the peer, if applicable. |
zone_awareness_id | string | zone_awareness_id is the zone awareness ID of the peer. | |
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. | |
allowed_ips | string | repeated | allowed_ips is the list of allowed IPs for the peer. |
allowed_routes | string | repeated | allowed_routes is the list of allowed routes for the peer. |
ice | bool | ice indicates whether the connection to this peer should be established over ICE. |
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. |
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. |
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. |
ADMIN_API | 4 | ADMIN_API is the feature for the admin API. |
PEER_DISCOVERY | 5 | PEER_DISCOVERY is the feature for peer discovery. |
METRICS | 6 | METRICS is the feature for exposing metrics. |
ICE_NEGOTIATION | 7 | ICE_NEGOTIATION is the feature for ICE negotiation. |
TURN_SERVER | 8 | TURN_SERVER is the feature for TURN server. |
MESH_DNS | 9 | MESH_DNS is the feature for mesh DNS. |
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. |
Snapshot | SnapshotRequest | SnapshotResponse | Snapshot is used to create a snapshot of the current state of the mesh. The snapshot can be used to restore the mesh state. |
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/mesh.proto
GetNodeRequest
GetNodeRequest is a request to get a node.
Field | Type | Label | Description |
---|---|---|---|
id | string | id is the ID of the node. |
MeshEdge
MeshEdge is an edge between two nodes.
Field | Type | Label | Description |
---|---|---|---|
source | string | source is the source node. | |
target | string | target is the target node. | |
weight | int32 | weight is the weight of the edge. | |
attributes | MeshEdge.AttributesEntry | repeated | attributes is a list of attributes for the edge. |
MeshEdge.AttributesEntry
Field | Type | Label | Description |
---|---|---|---|
key | string | ||
value | string |
MeshEdges
MeshEdges is a list of edges.
Field | Type | Label | Description |
---|---|---|---|
items | MeshEdge | repeated | items is the list of edges. |
MeshGraph
MeshGraph is a graph of nodes.
Field | Type | Label | Description |
---|---|---|---|
nodes | string | repeated | nodes is the list of nodes. |
edges | MeshEdge | repeated | edges is the list of edges. |
dot | string | dot is the DOT representation of the graph. |
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. | |
wireguard_endpoints | string | repeated | wireguard_endpoints is a list of WireGuard endpoints for the node. |
zone_awareness_id | string | zone_awareness_id is the zone awareness ID of 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. | |
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. |
EdgeAttributes
EdgeAttributes are pre-defined edge attributes. They should
be used as their string values.
Name | Number | Description |
---|---|---|
EDGE_ATTRIBUTE_UNKNOWN | 0 | EDGE_ATTRIBUTE_UNKNOWN is an unknown edge attribute. |
EDGE_ATTRIBUTE_ICE | 1 | EDGE_ATTRIBUTE_ICE is an ICE edge attribute. |
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. |
GetMeshGraph | .google.protobuf.Empty | MeshGraph | GetMeshGraph fetches the mesh graph. It returns a list of nodes, edges, and a rendering in the dot format. |
v1/rbac.proto
Group
Group is a group of subjects.
Field | Type | Label | Description |
---|---|---|---|
name | string | name is the name of the group. | |
subjects | Subject | repeated | subjects is the list of subjects in the group. |
Groups
Groups is a list of groups.
Field | Type | Label | Description |
---|---|---|---|
items | Group | repeated | items is the list of groups. |
RBACAction
RBACAction is an action that can be performed on a resource. It is used by implementations
to evaluate rules.
Field | Type | Label | Description |
---|---|---|---|
resource | RuleResource | resource is the resource on which the action is performed. | |
resource_name | string | resource_name is the name of the resource on which the action is performed. | |
verb | RuleVerb | verb is the verb that is performed on the resource. |
Role
Role is a role that can be assigned to a subject.
Field | Type | Label | Description |
---|---|---|---|
name | string | name is the name of the role. | |
rules | Rule | repeated | rules is the list of rules that apply to the role. |
RoleBinding
RoleBinding is a binding of a role to one or more subjects.
Field | Type | Label | Description |
---|---|---|---|
name | string | name is the name of the role binding. | |
role | string | role is the name of the role to which the binding applies. | |
subjects | Subject | repeated | subjects is the list of subjects to which the binding applies. |
RoleBindings
RoleBindings is a list of role bindings.
Field | Type | Label | Description |
---|---|---|---|
items | RoleBinding | repeated | items is the list of role bindings. |
Roles
Roles is a list of roles.
Field | Type | Label | Description |
---|---|---|---|
items | Role | repeated | items is the list of roles. |
Rule
Rule is a rule that applies to a resource.
Field | Type | Label | Description |
---|---|---|---|
resources | RuleResource | repeated | resources is the resources to which the rule applies. |
resource_names | string | repeated | resource_names is the list of resource names to which the rule applies. |
verbs | RuleVerb | repeated | verbs is the list of verbs that apply to the resource. |
Subject
Subject is a subject to which a role can be bound.
Field | Type | Label | Description |
---|---|---|---|
name | string | name is the name of the subject. | |
type | SubjectType | type is the type of the subject. |
RuleResource
RuleResource is the resource type for a rule.
Name | Number | Description |
---|---|---|
RESOURCE_UNKNOWN | 0 | RESOURCE_UNKNOWN is an unknown resource. |
RESOURCE_VOTES | 1 | RESOURCE_VOTES is the resource for voting in raft elections. The only verb evaluated for this resource is PUT. |
RESOURCE_ROLES | 2 | RESOURCE_ROLES is the resource for managing roles. |
RESOURCE_ROLE_BINDINGS | 3 | RESOURCE_ROLE_BINDINGS is the resource for managing role bindings. |
RESOURCE_GROUPS | 4 | RESOURCE_GROUPS is the resource for managing groups. |
RESOURCE_NETWORK_ACLS | 5 | RESOURCE_NETWORK_ACLS is the resource for managing network ACLs. |
RESOURCE_ROUTES | 6 | RESOURCE_ROUTES is the resource for managing routes. |
RESOURCE_DATA_CHANNELS | 7 | RESOURCE_DATA_CHANNELS is the resource for creating data channels. |
RESOURCE_EDGES | 8 | RESOURCE_EDGES is the resource for managing edges. |
RESOURCE_ALL | 999 | RESOURCE_ALL is a wildcard resource that matches all resources. |
RuleVerb
RuleVerb is the verb type for a rule.
Name | Number | Description |
---|---|---|
VERB_UNKNOWN | 0 | VERB_UNKNOWN is an unknown verb. |
VERB_PUT | 1 | VERB_PUT is the verb for creating or updating a resource. |
VERB_GET | 2 | VERB_GET is the verb for getting a resource. |
VERB_DELETE | 3 | VERB_DELETE is the verb for deleting a resource. |
VERB_ALL | 999 | VERB_ALL is a wildcard verb that matches all verbs. |
SubjectType
SubjectType is the type of a subject.
Name | Number | Description |
---|---|---|
SUBJECT_UNKNOWN | 0 | SUBJECT_UNKNOWN is an unknown subject type. |
SUBJECT_NODE | 1 | SUBJECT_NODE is a subject type for a node. |
SUBJECT_USER | 2 | SUBJECT_USER is a subject type for a user. |
SUBJECT_GROUP | 3 | SUBJECT_GROUP is a subject type for a group. |
SUBJECT_ALL | 999 | SUBJECT_ALL is a wildcard subject type that matches all subject types. It can be used with a subject named '*' to match all subjects. |
v1/network_acls.proto
NetworkACL
NetworkACL is a network ACL.
Field | Type | Label | Description |
---|---|---|---|
name | string | name is the name of the ACL. | |
priority | int32 | priority is the priority of the ACL. ACLs with higher priority are evaluated first. | |
action | ACLAction | action is the action to take when a request matches the ACL. | |
source_nodes | string | repeated | source_nodes is a list of source nodes to match against. If empty, all nodes are matched. Groups can be specified with the prefix "group:". |
destination_nodes | string | repeated | destination_nodes is a list of destination nodes to match against. If empty, all nodes are matched. |
source_cidrs | string | repeated | source_cidrs is a list of source CIDRs to match against. If empty, all CIDRs are matched. |
destination_cidrs | string | repeated | destination_cidrs is a list of destination CIDRs to match against. If empty, all CIDRs are matched. |
protocols | string | repeated | protocols is a list of protocols to match against. If empty, all protocols are matched. Protocols can be specified by name or number. |
ports | uint32 | repeated | ports is a list of ports to match against. If empty, all ports are matched. |
NetworkACLs
NetworkACLs is a list of network ACLs.
Field | Type | Label | Description |
---|---|---|---|
items | NetworkACL | repeated | items is the list of network ACLs. |
NetworkAction
NetworkAction is an action that can be performed on a network resource. It is used
by implementations to evaluate network ACLs.
Field | Type | Label | Description |
---|---|---|---|
src_node | string | src_node is the source node of the action. | |
src_cidr | string | src_cidr is the source CIDR of the action. | |
dst_node | string | dst_node is the destination node of the action. | |
dst_cidr | string | dst_cidr is the destination CIDR of the action. | |
protocol | string | protocol is the protocol of the action. | |
port | uint32 | port is the port of the action. |
Route
Route is a route that is broadcasted by one or more nodes.
Field | Type | Label | Description |
---|---|---|---|
name | string | name is the name of the route. | |
node | string | node is the node that broadcasts the route. A group can be specified with the prefix "group:". | |
destination_cidrs | string | repeated | destination_cidrs are the destination CIDRs of the route. |
next_hop_node | string | next_hop_node is an optional node that is used as the next hop for the route. |
Routes
Routes is a list of routes.
Field | Type | Label | Description |
---|---|---|---|
items | Route | repeated | items is the list of routes. |
ACLAction
ACLAction is the action to take when a request matches an ACL.
Name | Number | Description |
---|---|---|
ACTION_UNKNOWN | 0 | ACTION_UNKNOWN is the default action for ACLs. It is synonymous with ACTION_DENY. |
ACTION_ACCEPT | 1 | ACTION_ACCEPT allows the request to proceed. |
ACTION_DENY | 2 | ACTION_DENY denies the request. |
v1/admin.proto
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 |
---|---|---|---|
PutRole | Role | .google.protobuf.Empty | PutRole creates or updates a role. |
DeleteRole | Role | .google.protobuf.Empty | DeleteRole deletes a role. |
GetRole | Role | Role | GetRole gets a role. |
ListRoles | .google.protobuf.Empty | Roles | ListRoles gets all roles. |
PutRoleBinding | RoleBinding | .google.protobuf.Empty | PutRoleBinding creates or updates a role binding. |
DeleteRoleBinding | RoleBinding | .google.protobuf.Empty | DeleteRoleBinding deletes a role binding. |
GetRoleBinding | RoleBinding | RoleBinding | GetRoleBinding gets a role binding. |
ListRoleBindings | .google.protobuf.Empty | RoleBindings | ListRoleBindings gets all role bindings. |
PutGroup | Group | .google.protobuf.Empty | PutGroup creates or updates a group. |
DeleteGroup | Group | .google.protobuf.Empty | DeleteGroup deletes a group. |
GetGroup | Group | Group | GetGroup gets a group. |
ListGroups | .google.protobuf.Empty | Groups | ListGroups gets all groups. |
PutNetworkACL | NetworkACL | .google.protobuf.Empty | PutNetworkACL creates or updates a network ACL. |
DeleteNetworkACL | NetworkACL | .google.protobuf.Empty | DeleteNetworkACL deletes a network ACL. |
GetNetworkACL | NetworkACL | NetworkACL | GetNetworkACL gets a network ACL. |
ListNetworkACLs | .google.protobuf.Empty | NetworkACLs | ListNetworkACLs gets all network ACLs. |
PutRoute | Route | .google.protobuf.Empty | PutRoute creates or updates a route. |
DeleteRoute | Route | .google.protobuf.Empty | DeleteRoute deletes a route. |
GetRoute | Route | Route | GetRoute gets a route. |
ListRoutes | .google.protobuf.Empty | Routes | ListRoutes gets all routes. |
PutEdge | MeshEdge | .google.protobuf.Empty | PutEdge creates or updates an edge between two nodes. |
DeleteEdge | MeshEdge | .google.protobuf.Empty | DeleteEdge deletes an edge between two nodes. |
GetEdge | MeshEdge | MeshEdge | GetEdge gets an edge between two nodes. |
ListEdges | .google.protobuf.Empty | MeshEdges | ListEdges gets all current edges. |
v1/peer_discovery.proto
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/raft.proto
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. |
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. |
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/plugin.proto
AuthenticationRequest
AuthenticationRequest is the message containing an authentication request.
Field | Type | Label | Description |
---|---|---|---|
headers | AuthenticationRequest.HeadersEntry | repeated | headers are the headers of the request. |
certificates | bytes | repeated | certificates are the DER encoded certificates of the request. |
AuthenticationRequest.HeadersEntry
Field | Type | Label | Description |
---|---|---|---|
key | string | ||
value | string |
AuthenticationResponse
AuthenticationResponse is the message containing an authentication response.
Field | Type | Label | Description |
---|---|---|---|
id | string | id is the id of the authenticated user. |
DataSnapshot
DataSnapshot is the message containing a snapshot of the data.
Field | Type | Label | Description |
---|---|---|---|
term | uint64 | term is the term of the log entry. | |
index | uint64 | index is the index of the log entry. | |
data | bytes | data is the snapshot of the data. |
Event
Event is the message containing a watch event.
Field | Type | Label | Description |
---|---|---|---|
type | WatchEvent | type is the type of the watch event. | |
node | MeshNode | node is the node that the event is about. |
PluginConfiguration
PluginConfiguration is the message containing the configuration of a plugin.
Field | Type | Label | Description |
---|---|---|---|
config | google.protobuf.Struct | Config is the configuration of the plugin. |
PluginInfo
PluginInfo is the information of a plugin.
Field | Type | Label | Description |
---|---|---|---|
name | string | Name is the name of the plugin. | |
version | string | Version is the version of the plugin. | |
description | string | Description is the description of the plugin. | |
capabilities | PluginCapability | repeated | Capabilities is the capabilities of the plugin. |
StoreLogRequest
StoreLogRequest is the message containing a raft log entry.
Field | Type | Label | Description |
---|---|---|---|
term | uint64 | term is the term of the log entry. | |
index | uint64 | index is the index of the log entry. | |
log | RaftLogEntry | log is the log entry. |
PluginCapability
PluginCapability is the capabilities of a plugin.
Name | Number | Description |
---|---|---|
PLUGIN_CAPABILITY_UNKNOWN | 0 | PLUGIN_CAPABILITY_UNKNOWN is the default value of PluginCapability. |
PLUGIN_CAPABILITY_STORE | 1 | PLUGIN_CAPABILITY_STORE indicates that the plugin is a raft store plugin. |
PLUGIN_CAPABILITY_AUTH | 2 | PLUGIN_CAPABILITY_AUTH indicates that the plugin is an auth plugin. |
PLUGIN_CAPABILITY_WATCH | 3 | PLUGIN_CAPABILITY_WATCH indicates that the plugin wants to receive watch events. |
WatchEvent
WatchEvent is the type of a watch event.
Name | Number | Description |
---|---|---|
WATCH_EVENT_UNKNOWN | 0 | WATCH_EVENT_UNKNOWN is the default value of WatchEvent. |
WATCH_EVENT_NODE_JOIN | 1 | WATCH_EVENT_NODE_JOIN indicates that a node has joined the cluster. |
WATCH_EVENT_NODE_LEAVE | 2 | WATCH_EVENT_NODE_LEAVE indicates that a node has left the cluster. |
WATCH_EVENT_LEADER_CHANGE | 3 | WATCH_EVENT_LEADER_CHANGE indicates that the leader of the cluster has changed. |
Plugin
Plugin is the service definiteion for a WebMesh plugin.
Method Name | Request Type | Response Type | Description |
---|---|---|---|
GetInfo | .google.protobuf.Empty | PluginInfo | GetInfo returns the information for the plugin. |
Configure | PluginConfiguration | .google.protobuf.Empty | Configure configures the plugin. |
Store | StoreLogRequest | RaftApplyResponse | Store dispatches a Raft log entry for storage. |
RestoreSnapshot | DataSnapshot | .google.protobuf.Empty | RestoreSnapshot should drop any existing state and restore from the snapshot. |
Authenticate | AuthenticationRequest | AuthenticationResponse | Authenticate authenticates a request. |
Emit | Event | .google.protobuf.Empty | Emit handles a watch event. |
v1/webrtc.proto
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. A port of 0 coupled with the udp protocol indicates forwarding to the WireGuard interface. | |
answer | string | answer is the answer to the offer. | |
candidate | string | candidate is an ICE candidate. |
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) |