145 lines
4.4 KiB
Markdown
145 lines
4.4 KiB
Markdown
# What is respondd?
|
||
|
||
## Introduction
|
||
respondd is a server distributing information within a network.
|
||
|
||
For doing so, respondd spawns a UDP socket (in Gluon 1001/udp), optionally joining a multicast group. When a request is received, the information requested is transmitted to the requester.
|
||
|
||
All information is organized in a non-hierarchical namespace. Each entry identifies a *request name* (e.g. `statistics`, `nodeinfo`, ...) implemented by at least one "provider" C module.
|
||
The respond is the result of merging the outputs of all providers for the given request name.
|
||
|
||
Some providers are implemented in [/package/gluon-respondd](https://github.com/freifunk-gluon/gluon/tree/master).
|
||
|
||
## Usage
|
||
```
|
||
respondd [-p <port>] [-g <group> -i <if0> [-i <if1> ..]] [-d <dir>]
|
||
-p <int> port number to listen on
|
||
-g <ip6> multicast group, e.g. ff02::2:1001
|
||
-i <string> interface on which the group is joined
|
||
-d <string> data provider directory (default: current directory)
|
||
-h this help
|
||
```
|
||
|
||
## Procotol
|
||
Request and response are encoded as byte strings. These strings are sent as UDP packets. Fragmentation is not supported (except by the IP stack), responses are compressed using the *deflate* algorithm.
|
||
|
||
- The request is the the word '`GET`' followed by any number of request name, separated by spaces.
|
||
- The response is a compressed JSON document. The top level object will contain a property for each
|
||
requested name, the rest of the structure is determined by the actual data.
|
||
- (Using just a single request name, without '`GET`', as request will return the data uncompressed
|
||
and without an enclosing object. This kind of request is deprecated.)
|
||
|
||
### Example
|
||
Requesting `nodeinfo` as implemented in the Gluon modules.
|
||
|
||
#### Request
|
||
```
|
||
GET nodeinfo
|
||
```
|
||
|
||
#### Response (decompressed)
|
||
```json
|
||
{
|
||
"nodeinfo": {
|
||
"software": {
|
||
"autoupdater": {
|
||
"branch": "stable",
|
||
"enabled": true
|
||
},
|
||
"batman-adv": {
|
||
"version": "2015.1",
|
||
"compat": 15
|
||
},
|
||
"fastd": {
|
||
"version": "v17",
|
||
"enabled": false
|
||
},
|
||
"firmware": {
|
||
"base": "gluon-v2016.1.5-8-gdeac14e",
|
||
"release": "20160615"
|
||
},
|
||
"status-page": {
|
||
"api": 1
|
||
}
|
||
},
|
||
"network": {
|
||
"addresses": [
|
||
"fda0:cab1:e1e5:5116:eade:27ff:fe65:a5af",
|
||
"fe80::eade:27ff:fe65:a5af",
|
||
"2a03:2260:3011:1160:eade:27ff:fe65:a5af"
|
||
],
|
||
"mesh": {
|
||
"bat0": {
|
||
"interfaces": {
|
||
"wireless": [
|
||
"ea:e3:29:65:a5:af",
|
||
"ea:e3:28:65:a5:af"
|
||
],
|
||
"other": [
|
||
"ea:df:27:65:a5:af"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"mac": "e8:de:27:65:a5:af"
|
||
},
|
||
"location": {
|
||
"latitude": 51.10727924,
|
||
"longitude": 7.00933367
|
||
},
|
||
"owner": {
|
||
"contact": "me@petabyteboy.de"
|
||
},
|
||
"system": {
|
||
"site_code": "lln"
|
||
},
|
||
"node_id": "e8de2765a5af",
|
||
"hostname": "PetaByteBoy",
|
||
"hardware": {
|
||
"model": "TP-Link TL-WDR3600 v1",
|
||
"nproc": 1
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Implementing modules
|
||
|
||
respondd providers are C modules (shared objects). These modules should include
|
||
\<json-c/json.h> and \<respondd.h>, the latter of which provides the following definitions:
|
||
|
||
typedef struct json_object * (*respondd_provider)(void);
|
||
|
||
struct respondd_provider_info {
|
||
const char *request;
|
||
const respondd_provider provider;
|
||
};
|
||
|
||
extern const struct respondd_provider_info respondd_providers[];
|
||
|
||
|
||
The module must define the array `respondd_providers`, e.g. like this:
|
||
|
||
static struct json_object * respondd_provider_nodeinfo(void) {
|
||
...
|
||
}
|
||
|
||
static struct json_object * respondd_provider_statistics(void) {
|
||
...
|
||
}
|
||
|
||
const struct respondd_provider_info respondd_providers[] = {
|
||
{"nodeinfo", respondd_provider_nodeinfo},
|
||
{"statistics", respondd_provider_statistics},
|
||
{}
|
||
};
|
||
|
||
The array must be terminated with an empty entry. The provider for each
|
||
request type must return a [JSON-C] JSON object. This JSON object must have exactly 1
|
||
reference, and all other memory must be freed by the provider before returning.
|
||
|
||
The JSON objects returned by different provider modules for the same request type
|
||
are merged.
|
||
|
||
[JSON-C]: https://github.com/json-c/json-c/wiki
|