README.md

# Cloud IP Validator

Система проверки освобождённых публичных IPv4-адресов перед их повторной
выдачей: каждый адрес временно привязывается как Floating IP к
ВМ-валидатору в облаке (OpenStack) и проверяется одновременно в двух
направлениях — исходящий трафик валидатора (egress: HTTPS/ICMP/опционально
SSH до внешних целей) и входящая доступность самого адреса с нескольких
независимых внешних площадок (inbound: TCP 22/80/443/8080 + ICMP). Итог по
каждому адресу — `pass`/`partial`/`fail`, с полной историей проверок,
которая сохраняется даже после того, как адрес убрали из очереди (см.
[«Реестр адресов»](docs/USAGE.md#реестр-адресов-и-глубина-истории)).

## Роли компонентов

| Компонент | Роль | Состояние | Где работает |
|---|---|---|---|
| `control-api` | Управляющий сервис: ведёт очередь адресов и реестр их истории, назначает валидаторов, агрегирует результаты. Единственная точка, с которой общаются все остальные компоненты. | Хранит (SQLite) | Одна управляющая машина |
| `validator-agent` | Привязывает к себе выданный Floating IP и прогоняет egress-проверки до внешних целей. | Без состояния | Каждая ВМ-валидатор в облаке |
| `prober` | Проверяет входящую доступность адреса снаружи (TCP/ICMP) — с независимой от облака сети. | Без состояния | Каждая внешняя тестовая площадка |
| `admin-dashboard` | Браузерная админ-панель — то же самое, что доступно через API `control-api`, но графически. Опционален. | Без состояния | Любая машина с сетевым доступом к `control-api` |

Все четыре общаются между собой **только** через HTTP API `control-api` —
прямых связей между остальными компонентами нет. Подробная схема
control/data plane — в [docs/DIAGRAMS.md](docs/DIAGRAMS.md).

## Документация

| Документ | Для чего |
|---|---|
| [docs/SETUP.md](docs/SETUP.md) | Развёртывание с нуля: бинарники или сборка из исходников, конфигурация, systemd **и** Docker/docker-compose — пошагово |
| [docs/USAGE.md](docs/USAGE.md) | Повседневная работа: постановка адресов в очередь, сканирование Floating IP, наблюдение за статусом, реестр и история, разбор результатов |
| [docs/API.md](docs/API.md) | Спецификация HTTP API `control-api` и примеры запросов (curl) |
| [docs/DASHBOARD.md](docs/DASHBOARD.md) | Устройство `admin-dashboard`: страницы, поиск/фильтр, обработка ошибок |
| [docs/DIAGRAMS.md](docs/DIAGRAMS.md) | Диаграммы потоков данных: control plane, egress-проверка, телеметрия |
| [docs/LOCAL_E2E.md](docs/LOCAL_E2E.md) | Полностью офлайн-прогон всей системы одним скриптом — без реального облака и интернета |
| [docs/CONTROL_DATA_PLANE.html](docs/CONTROL_DATA_PLANE.html) | Презентационные схемы control/data plane для docker-compose-деплоя — открыть в браузере |

## Быстрый старт

Посмотреть систему в работе без реального облака (60 секунд):

```bash
go build ./... && go test ./...
scripts/run-local-e2e.sh
```

Поднимет все компоненты как локальные процессы (`openstack.mode: mock`) и
прогонит тестовый адрес через полный цикл проверки. Подробности —
[docs/LOCAL_E2E.md](docs/LOCAL_E2E.md).

Для реального стенда (systemd-юниты или Docker/docker-compose, на одной
машине или распределённо) — по шагам в
[docs/SETUP.md](docs/SETUP.md), начиная с
[«Получение бинарников»](docs/SETUP.md#получение-бинарников).