From 6cc0c617b4602ac800bfaf538daf0d44c4ee5b2b Mon Sep 17 00:00:00 2001 From: Lan Tian Date: Sun, 17 Jan 2021 16:16:41 +0800 Subject: [PATCH] frontend: add API for server list --- API.md | 202 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 152 +----------------------------------- frontend/api.go | 21 ++++- 3 files changed, 220 insertions(+), 155 deletions(-) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..ada26d2 --- /dev/null +++ b/API.md @@ -0,0 +1,202 @@ +# Bird-lg-go API documentation + +The frontend provides an API for running BIRD/traceroute/whois queries. + +API Endpoint: `https://your.frontend.com/api/` (the last slash must not be omitted!) + +Requests are sent as POSTS with JSON bodies. + +## Table of Contents + + * [Bird-lg-go API documentation](#bird-lg-go-api-documentation) + * [Table of Contents](#table-of-contents) + * [Request fields](#request-fields) + * [Example request of type bird](#example-request-of-type-bird) + * [Example request of type server_list](#example-request-of-type-server_list) + * [Response fields (when type is summary)](#response-fields-when-type-is-summary) + * [Fields for apiSummaryResultPair](#fields-for-apisummaryresultpair) + * [Fields for SummaryRowData](#fields-for-summaryrowdata) + * [Example response](#example-response) + * [Response fields (when type is bird, traceroute, whois or server_list)](#response-fields-when-type-is-bird-traceroute-whois-or-server_list) + * [Fields for apiGenericResultPair](#fields-for-apigenericresultpair) + * [Example response of type bird](#example-response-of-type-bird) + * [Example response of type server_list](#example-response-of-type-server_list) + +Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc) + +## Request fields + +| Name | Type | Value | +| ---- | ---- | -------- | +| `servers` | array of `string` | List of servers to be queried | +| `type` | `string` | Can be `summary`, `bird`, `traceroute`, `whois` or `server_list` | +| `args` | `string` | Arguments to be passed, see below | + +Argument examples for each type: + +- `summary`: `args` is ignored. Recommended to set to empty string. +- `bird`: `args` is the command to be passed to bird, e.g. `show route for 8.8.8.8` +- `traceroute`: `args` is the traceroute target, e.g. `8.8.8.8` or `google.com` +- `whois`: `args` is the whois target, e.g. `8.8.8.8` or `google.com` +- `server_list`: `args` is ignored. In addition, `servers` is also ignored. + +### Example request of type `bird` + +```json +{ + "servers": [ + "alpha" + ], + "type": "bird", + "args": "show route for 8.8.8.8" +} +``` + +### Example request of type `server_list` + +```json +{ + "servers": [], + "type": "server_list", + "args": "" +} +``` + +## Response fields (when `type` is `summary`) + +| Name | Type | Value | +| ---- | ---- | -------- | +| `error` | `string` | Error message when something is wrong. Empty when everything is good | +| `result` | array of `apiSummaryResultPair` | See below | + +### Fields for `apiSummaryResultPair` + +| Name | Type | Value | +| ---- | ---- | -------- | +| `server` | `string` | Name of the server | +| `data` | array of `SummaryRowData` | Summaries of the server, see below | + +### Fields for `SummaryRowData` + +All fields below is 1:1 correspondent to the output of `birdc show protocols`. + +| Name | Type | +| ---- | ---- | +| `name` | `string` | +| `proto` | `string` | +| `table` | `string` | +| `state` | `string` | +| `since` | `string` | +| `info` | `string` | + +### Example response + +Request: +```json +{ + "servers": [ + "alpha" + ], + "type": "summary", + "args": "" +} +``` + +Response: + +```json +{ + "error": "", + "result": [ + { + "server": "alpha", + "data": [ + { + "name": "bgp1", + "proto": "BGP", + "table": "---", + "state": "start", + "since": "2021-01-15 22:40:01", + "info": "Active Socket: Operation timed out" + }, + { + "name": "bgp2", + "proto": "BGP", + "table": "---", + "state": "start", + "since": "2021-01-03 08:15:48", + "info": "Established" + } + ] + } + ] +} +``` + +## Response fields (when `type` is `bird`, `traceroute`, `whois` or `server_list`) + +| Name | Type | Value | +| ---- | ---- | -------- | +| `error` | `string` | Error message, empty when everything is good | +| `result` | array of `apiGenericResultPair` | See below | + +### Fields for `apiGenericResultPair` + +| Name | Type | Value | +| ---- | ---- | -------- | +| `server` | `string` | Name of the server; is empty when type is `whois` | +| `data` | `string` | Result from the server; is empty when type is `server_list` | + +### Example response of type `bird` + +Request: + +```json +{ + "servers": [], + "type": "server_list", + "args": "" +} +``` + +Response: + +```json +{ + "error": "", + "result": [ + { + "server": "alpha", + "data": "BIRD v2.0.7-137-g61dae32b\nRouter ID is 1.2.3.4\nCurrent server time is 2021-01-17 04:21:14.792\nLast reboot on 2021-01-03 08:15:48.494\nLast reconfiguration on 2021-01-17 00:49:10.573\nDaemon is up and running\n" + } + ] +} +``` + +### Example response of type `server_list` + +Request: + +```json +{ + "servers": [ + "alpha" + ], + "type": "bird", + "args": "show status" +} +``` + +Response: + +```json +{ + "error": "", + "result": [ + { + "server": "gigsgigscloud", + "data": "" + } + ] +} +``` diff --git a/README.md b/README.md index 4f7238b..5cf1867 100644 --- a/README.md +++ b/README.md @@ -12,14 +12,6 @@ An alternative implementation for [bird-lg](https://github.com/sileht/bird-lg) w * [Proxy](#proxy) * [Advanced Features](#advanced-features) * [API](#api) - * [Request fields](#request-fields) - * [Response fields (when type is summary)](#response-fields-when-type-is-summary) - * [Fields for apiSummaryResultPair](#fields-for-apisummaryresultpair) - * [Fields for SummaryRowData](#fields-for-summaryrowdata) - * [Example response](#example-response) - * [Response fields (when type is bird, traceroute or whois)](#response-fields-when-type-is-bird-traceroute-or-whois) - * [Fields for apiGenericResultPair](#fields-for-apigenericresultpair) - * [Example response](#example-response-1) * [Telegram Bot Webhook](#telegram-bot-webhook) * [Example of setting the webhook](#example-of-setting-the-webhook) * [Supported commands](#supported-commands) @@ -118,149 +110,7 @@ You can use source IP restriction to increase security. You should also bind the The frontend provides an API for running BIRD/traceroute/whois queries. -API Endpoint: `https://your.frontend.com/api/` (the last slash must not be omitted!) - -Requests are sent as POSTS with JSON bodies. - -#### Request fields - -| Name | Type | Value | -| ---- | ---- | -------- | -| `servers` | array of `string` | List of servers to be queried | -| `type` | `string` | Can be `summary`, `bird`, `traceroute` or `whois` | -| `args` | `string` | Arguments to be passed, see below | - -Argument examples for each type: - -- `summary`: `args` is ignored. Recommended to set to empty string. -- `bird`: `args` is the command to be passed to bird, e.g. `show route for 8.8.8.8` -- `traceroute`: `args` is the traceroute target, e.g. `8.8.8.8` or `google.com` -- `whois`: `args` is the whois target, e.g. `8.8.8.8` or `google.com` - -Example request: - -```json -{ - "servers": [ - "alpha" - ], - "type": "bird", - "args": "show route for 8.8.8.8" -} -``` - -#### Response fields (when `type` is `summary`) - -| Name | Type | Value | -| ---- | ---- | -------- | -| `error` | `string` | Error message when something is wrong. Empty when everything is good | -| `result` | array of `apiSummaryResultPair` | See below | - -##### Fields for `apiSummaryResultPair` - -| Name | Type | Value | -| ---- | ---- | -------- | -| `server` | `string` | Name of the server | -| `data` | array of `SummaryRowData` | Summaries of the server, see below | - -##### Fields for `SummaryRowData` - -All fields below is 1:1 correspondent to the output of `birdc show protocols`. - -| Name | Type | -| ---- | ---- | -| `name` | `string` | -| `proto` | `string` | -| `table` | `string` | -| `state` | `string` | -| `since` | `string` | -| `info` | `string` | - -##### Example response - -Request: -```json -{ - "servers": [ - "alpha" - ], - "type": "summary", - "args": "" -} -``` - -Response: - -```json -{ - "error": "", - "result": [ - { - "server": "alpha", - "data": [ - { - "name": "bgp1", - "proto": "BGP", - "table": "---", - "state": "start", - "since": "2021-01-15 22:40:01", - "info": "Active Socket: Operation timed out" - }, - { - "name": "bgp2", - "proto": "BGP", - "table": "---", - "state": "start", - "since": "2021-01-03 08:15:48", - "info": "Established" - } - ] - } - ] -} -``` - -#### Response fields (when `type` is `bird`, `traceroute` or `whois`) - -| Name | Type | Value | -| ---- | ---- | -------- | -| `error` | `string` | Error message, empty when everything is good | -| `result` | array of `apiGenericResultPair` | See below | - -##### Fields for `apiGenericResultPair` - -| Name | Type | Value | -| ---- | ---- | -------- | -| `server` | `string` | Name of the server; is empty when type is `whois` | -| `data` | `string` | Result from the server | - -##### Example response - -Request: - -```json -{ - "servers": [ - "alpha" - ], - "type": "bird", - "args": "show status" -} -``` - -Response: - -```json -{ - "error": "", - "result": [ - { - "server": "alpha", - "data": "BIRD v2.0.7-137-g61dae32b\nRouter ID is 1.2.3.4\nCurrent server time is 2021-01-17 04:21:14.792\nLast reboot on 2021-01-03 08:15:48.494\nLast reconfiguration on 2021-01-17 00:49:10.573\nDaemon is up and running\n" - } - ] -} -``` +See [API docs](API.md) for detailed information. ### Telegram Bot Webhook diff --git a/frontend/api.go b/frontend/api.go index ec5d357..9d2380e 100644 --- a/frontend/api.go +++ b/frontend/api.go @@ -28,10 +28,11 @@ type apiResponse struct { } var apiHandlerMap = map[string](func(request apiRequest) apiResponse){ - "summary": apiSummaryHandler, - "bird": apiGenericHandlerFactory("bird"), - "traceroute": apiGenericHandlerFactory("traceroute"), - "whois": apiWhoisHandler, + "summary": apiSummaryHandler, + "bird": apiGenericHandlerFactory("bird"), + "traceroute": apiGenericHandlerFactory("traceroute"), + "whois": apiWhoisHandler, + "server_list": apiServerListHandler, } func apiGenericHandlerFactory(endpoint string) func(request apiRequest) apiResponse { @@ -50,6 +51,18 @@ func apiGenericHandlerFactory(endpoint string) func(request apiRequest) apiRespo } } +func apiServerListHandler(request apiRequest) apiResponse { + var response apiResponse + + for _, server := range setting.servers { + response.Result = append(response.Result, apiGenericResultPair{ + Server: server, + }) + } + + return response +} + func apiSummaryHandler(request apiRequest) apiResponse { results := batchRequest(request.Servers, "bird", "show protocols") var response apiResponse