REST: peers
The endpoints under /node list the nodes this node knows about and let an operator add or remove one. They are
part of the REST interface and need the bearer token like every other endpoint. How nodes find
and talk to each other is described in Peer-to-peer network protocol.
Addresses. A node is written host:port, with a host name or an IP address. In a path the address is the
last segment; in the body of POST /node it is plain text. An address that cannot be read, such as one with a port
above 65535, or whose host does not resolve, is answered with 400 and an empty body.
Configured nodes. A node is configured when an operator added it, or when it is a seed: an address that a seed name resolves to in the current round, or the one it last resolved to while its lookup fails. A seed address that no seed name resolves to any more stays configured only when it was added here; otherwise it leaves the known nodes, unless a connection or an open stream still ties it to this node. A configured node stays known when it cannot be reached and is dialed again. A node that only a peer told of is known but not configured; adding it here makes it configured. The node keeps the added nodes in memory only, so they are gone after it restarts.
A node has address, details (the protocols it offered and its version), nsPing, the round trip of its last
ping in nanoseconds, uri, its address as the path /<ip>:<port>, and me, whether it is this node.
GET /node
| Answer | Meaning |
|---|---|
| 200 | A list of the nodes the node knows, configured or not |
| 204 | It knows none |
GET /node/{address}
| Answer | Meaning |
|---|---|
| 200 | The node |
| 400 | The address cannot be read |
| 404 | The node does not know that node |
POST /node
The body is the address as plain text. The node is added to the nodes this node dials.
| Answer | Meaning |
|---|---|
| 201 | The node was new; Location is https://<resthost>:<restport>/<ip>:<port>, this node’s REST address followed by the added node’s address |
| 200 | The node was known already, as a peer told of it, and is configured from now on; Location is set as for 201 and the body is the text The node was already known, as a peer told of it, and is configured from now on |
| 409 | The node was configured before; a seed sent here stays configured from now on, also once no seed name resolves to it |
| 304 | The node refuses the address: it is this node |
| 400 | The address cannot be read |
hedgehog cli node-add prints the Location and, for a 200, the text after it. A 409 ends it with Conflict
and a 304 with The node did not take <address>, which is its own address or one it cannot use, both on standard
error and with exit code 1.
DELETE /node/{address}
Takes the node out of the nodes this node knows and out of the configured ones, then closes the connection this node dialed to it, if there is one. A seed comes back in the next round in which a seed name resolves to it.
| Answer | Meaning |
|---|---|
| 200 | The node is removed |
| 400 | The address cannot be read |
| 404 | The node does not know that node |
In the source
application/src/main/java/org/unigrid/hedgehog/server/rest/NodeResource.java: the four endpoints.application/src/main/java/org/unigrid/hedgehog/model/network/Topology.java: the nodes,addConfiguredandremoveConfigured.application/src/main/java/org/unigrid/hedgehog/model/network/Node.java: a node and how an address is read.