first commit

2026-05-25 16:45:01 +03:00
commit 61eadfcb0d
5 changed files with 428 additions and 0 deletions
@@ -0,0 +1,222 @@
+# 🛠️ 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`    | Не передан обязательный параметр    |
+