223 lines
5.8 KiB
Markdown
223 lines
5.8 KiB
Markdown
# 🛠️ testmontools
|
|
|
|
Лёгкий HTTP-сервис для сетевой диагностики. Оборачивает `ping`, `traceroute` и `curl` в REST API — удобно для мониторинга, дебага и автоматизации.
|
|
|
|
---
|
|
|
|
## 📋 Содержание
|
|
|
|
- [Требования](#требования)
|
|
- [Запуск](#запуск)
|
|
- [API Reference](#api-reference)
|
|
- [POST /testmontools/ping](#post-testmontoolsping)
|
|
- [POST /testmontools/traceroute](#post-testmontoolstraceroute)
|
|
- [POST /testmontools/curl](#post-testmontoolscurl)
|
|
- [POST /testmontools/all](#post-testmontoolsall)
|
|
- [Формат входных данных](#формат-входных-данных)
|
|
- [Примеры](#примеры)
|
|
|
|
---
|
|
|
|
## Требования
|
|
|
|
- Python 3.8+
|
|
- Flask
|
|
- Утилиты `ping`, `traceroute`, `curl` в системе
|
|
|
|
```bash
|
|
pip install flask
|
|
```
|
|
|
|
---
|
|
|
|
## Запуск
|
|
|
|
```bash
|
|
python app.py
|
|
```
|
|
|
|
Сервер стартует на `http://0.0.0.0:7088`.
|
|
|
|
---
|
|
|
|
## API Reference
|
|
|
|
Все эндпоинты принимают `Content-Type: application/json` и возвращают JSON.
|
|
|
|
### Формат входных данных
|
|
|
|
В теле каждого запроса передаётся одно из полей:
|
|
|
|
| Поле | Тип | Описание |
|
|
|--------|--------|--------------------------------------------|
|
|
| `url` | string | Полный URL (`https://example.com/path`) |
|
|
| `host` | string | Хост или IP (`example.com`, `8.8.8.8`) |
|
|
|
|
Если передан URL, хост извлекается автоматически там, где нужен именно он (ping, traceroute).
|
|
|
|
---
|
|
|
|
### POST /testmontools/ping
|
|
|
|
Запускает `ping -c 4` до указанного хоста.
|
|
|
|
**Запрос**
|
|
```json
|
|
{ "host": "example.com" }
|
|
```
|
|
|
|
**Ответ**
|
|
```json
|
|
{
|
|
"input": "example.com",
|
|
"resolved_host": "example.com",
|
|
"stdout": "PING example.com (93.184.216.34) ...",
|
|
"stderr": "",
|
|
"returncode": 0
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### POST /testmontools/traceroute
|
|
|
|
Запускает `traceroute` до указанного хоста.
|
|
|
|
**Запрос**
|
|
```json
|
|
{ "host": "8.8.8.8" }
|
|
```
|
|
|
|
**Ответ**
|
|
```json
|
|
{
|
|
"input": "8.8.8.8",
|
|
"resolved_host": "8.8.8.8",
|
|
"stdout": "traceroute to 8.8.8.8 (8.8.8.8), 30 hops max ...",
|
|
"stderr": "",
|
|
"returncode": 0
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### POST /testmontools/curl
|
|
|
|
Выполняет `curl` к указанному URL с подробными тайминговыми метриками.
|
|
|
|
**Запрос**
|
|
```json
|
|
{ "url": "https://example.com" }
|
|
```
|
|
|
|
Дополнительные параметры:
|
|
|
|
| Поле | Тип | Описание |
|
|
|-----------|---------|-----------------------------------------------|
|
|
| `headers` | boolean | Если `true` — запрашивает только заголовки (`-I`) |
|
|
|
|
**Ответ**
|
|
```json
|
|
{
|
|
"input": "https://example.com",
|
|
"url": "https://example.com",
|
|
"timing": {
|
|
"dns_lookup": 0.012,
|
|
"tcp_connect": 0.034,
|
|
"tls_handshake":0.098,
|
|
"pre_transfer": 0.099,
|
|
"first_byte": 0.215,
|
|
"total": 0.216,
|
|
"size_bytes": 1256,
|
|
"speed_bps": 5814,
|
|
"http_code": 200
|
|
},
|
|
"trace": "* Connected to example.com ...",
|
|
"body": "<!doctype html>...",
|
|
"returncode": 0
|
|
}
|
|
```
|
|
|
|
**Тайминговые поля**
|
|
|
|
| Поле | Описание |
|
|
|-----------------|---------------------------------------|
|
|
| `dns_lookup` | Время разрешения DNS (сек) |
|
|
| `tcp_connect` | Время установки TCP-соединения (сек) |
|
|
| `tls_handshake` | Время TLS-хендшейка (сек) |
|
|
| `pre_transfer` | Время до начала передачи (сек) |
|
|
| `first_byte` | Время до первого байта ответа (сек) |
|
|
| `total` | Общее время запроса (сек) |
|
|
| `size_bytes` | Размер скачанного тела (байт) |
|
|
| `speed_bps` | Скорость загрузки (байт/сек) |
|
|
| `http_code` | HTTP-код ответа |
|
|
|
|
---
|
|
|
|
### POST /testmontools/all
|
|
|
|
Запускает `ping`, `traceroute` и `curl` **параллельно** и возвращает сводный результат.
|
|
|
|
**Запрос**
|
|
```json
|
|
{ "url": "https://example.com" }
|
|
```
|
|
|
|
**Ответ**
|
|
```json
|
|
{
|
|
"input": "https://example.com",
|
|
"ping": { ... },
|
|
"traceroute": { ... },
|
|
"curl": { ... }
|
|
}
|
|
```
|
|
|
|
Структура каждого вложенного объекта совпадает с ответами соответствующих отдельных эндпоинтов.
|
|
|
|
---
|
|
|
|
## Примеры
|
|
|
|
**curl из терминала**
|
|
|
|
```bash
|
|
# Ping
|
|
curl -s -X POST http://localhost:7088/testmontools/ping \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"host": "google.com"}' | jq
|
|
|
|
# Только заголовки
|
|
curl -s -X POST http://localhost:7088/testmontools/curl \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"url": "https://google.com", "headers": true}' | jq
|
|
|
|
# Полная диагностика
|
|
curl -s -X POST http://localhost:7088/testmontools/all \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"url": "https://google.com"}' | jq
|
|
```
|
|
|
|
**Python**
|
|
|
|
```python
|
|
import requests
|
|
|
|
r = requests.post(
|
|
"http://localhost:7088/testmontools/all",
|
|
json={"url": "https://example.com"}
|
|
)
|
|
data = r.json()
|
|
print(data["curl"]["timing"]["first_byte"])
|
|
```
|
|
|
|
---
|
|
|
|
## Коды ответов
|
|
|
|
| HTTP-код | Описание |
|
|
|----------|-------------------------------------|
|
|
| `200` | Успешно, результат в теле ответа |
|
|
| `400` | Не передан обязательный параметр |
|
|
|