8345d896a6
Consists of a single, one-shot request, GET /restful/route/all.json, for the time being. A "newsince" request can be added later. Add a Markdown tech doc that specifies the new Route REST API and update the MDP tech doc a little. Add the 'routerestful' test script, which uses some test utility fuctions that have been factored out of the 'routing' test script into the new testdefs_routing.sh. Add the new 'allrestful' test script.
9.8 KiB
Route REST API
Serval Project, September 2016
Introduction
Every Serval DNA daemon running on a node in the Serval mesh network maintains its own dynamic routing table, which it uses to choose the network interface on which to send each outgoing MDP message. The mesh routing algorithm updates the routing table whenever Serval DNA receives an overlay packet and whenever system time advances. For more details, see Mesh Datagram Protocol.
The Serval DNA daemon gives applications access to its routing table via the Route REST API described in this document. Applications can use this information to:
- discover the current network neighbours
- discover all currently (and recently) reachable nodes
- estimate the quality of service to any given reachable node
Basic concepts
Routing table
Every node in the Serval mesh network maintains its own routing table, which identifies a single path to every reachable node. The mesh routing algorithm chooses the best path based on routing information received from other nodes along the path.
Whenever a node receives an overlay packet, it knows that, at the time the packet was received, there existed a direct incoming link from the transmitting node. It updates its routing table to mark the transmitter's primary SID as a neighbour.
Whenever a node receives nothing from a given neighbour for longer than a configured time interval, it presumes that the link is broken. It updates its routing table to mark the neighbour's primary SID as no longer a neighbour.
Tick
Every daemon ensures that all of its nearby nodes remain aware of its presence by sending regular overlay packets to every neighbour. Every overlay packet contains its own primary SID as the sender address.
Every network interface has a configured tick interval, which is the maximum time period that may elapse between messages sent to any neighbour on that interface. If no message has been sent to a given neighbour for a whole tick interval, then the daemon sends an empty overlay packet, called a tick packet, to the neighbour.
As a result, while an interface is quiescent (no traffic), depending on whether the link to each neighbour is broadcast or unicast, at every tick the daemon will send either a single broadcast Wi-Fi packet, or several unicast Wi-Fi packets, or a mixture.
Node
A node in the Serval mesh network is any device with its own link-layer address (eg, a UDP/IP address or a Wi-Fi MAC address) that is running a Serval DNA daemon configured to use that network interface.
Neighbour
A node's neighbour in the Serval mesh network is any node from which its Serval DNA daemon directly receives overlay packets through a network interface.
Note that a neighbour is not necessarily reachable, because wireless links are not always symmetrical; even though station A receives from station B, it does not necessarily mean that B can receive from A, because of factors like different transmitter power and antenna gain.
Link
A link is a one-way connection from a node to one of its neighbour nodes. Links are represented in the routing table by the primary SID of their receiving end.
A link may be either broadcast or unicast, which is chosen by the receiver node during link negotiation.
Each link is characterised by a metric that represents the dynamic link quality (eg, the proportion of recent packets successfully received). Every node dynamically computes the quality of all its incoming links by counting the gaps in the sequence numbers on received overlay packets. It continuously informs each neighbour node of the measured quality of its incoming link by periodically sending a routing message to each neighbour at a configured time interval.
Primary SID
Every node identifies itself by its primary SID, which is usually the SID of the first identity that was unlocked since the daemon was started.
Secondary SID
A node may have more than one SID, ie more than one unlocked identity. All its SIDs except the primary SID are called secondary.
A node announces all of its secondary SIDs by representing them in its routing messages as reachable neighbours on a private network interface (ie, not available to other nodes) with a 100% link quality.
Routing message
Every node in the Serval mesh network informs other nodes of the presence and quality of all of its incoming and outgoing links by sending routing messages. A routing message is a one-hop message that goes to all neighbouring nodes but no further:
-
whenever a node detects the presence (received packet) or absence (timeout) of an incoming link, or revises the measured quality of an incoming link, it sends a routing message with the single link's state/quality to the single neighbour at the transmitting end of the link;
-
whenever a node receives a routing message from one of its neighbours, it incorporates the new link state (up/down) and quality information into its own routing table, re-evaluates its paths, and, shortly afterwards, sends a routing message containing the state/quality information of all its outgoing and incoming links to all of its neighbours.
Routing messages are not forwarded directly, but the information they carry propagates beyond the node's immediate neighbours because each neighbour, upon receiving a routing message, updates its own routing table and sends out its own routing messages that arise as a result of the update.
Path
A path is a one-way route from a sender node to a recipient node, expressed as a sequence of non-repeating links. The first link in a path always leads to a reachable neighbour node.
The routing algorithm constructs paths by choosing links whose existence and quality has been revealed by a recently-received routing message from a neighbour.
Reachable
A node in the Serval mesh network considers another node to be reachable if its own routing table contains a path to the second node.
REST Requests
GET /restful/route/all.json
Returns a list of all currently known identities, in JSON table format. The table columns are:
| heading | type | content |
|---|---|---|
sid |
string | the SID of the identity, as 64 uppercase hex digits |
did |
string or null |
the DID of the identity if known (eg, for a local keyring identity) |
name |
string or null |
the Name of the identity if known (eg, for a local keyring identity) |
is_self |
boolean | true if the identity is a self-identity, ie, in the local keyring |
reachable_broadcast |
boolean | true if the identity is reachable by broadcast link |
reachable_unicast |
boolean | true if the identity is reachable by unicast link |
reachable_indirect |
boolean | true if the identity is reachable only via another node |
interface |
string or null |
the name of the local network interface on which the identity is reachable |
hop_count |
integer | the number of hops to reach the identity |
first_hop |
string or null |
if hop_count > 1, then the SID of the first identity in the route |
penultimate_hop |
string or null |
if hop_count > 2, then the SID of the penultimate identity in the route |
Copyright 2015 Serval Project Inc.
Copyright 2016-2018 Flinders University
Available under the Creative Commons Attribution 4.0 International licence.