InfraTopoBuilder - это высокопроизводительный микросервис для асинхронного парсинга диагностических логов сети (формат
ibdiagnet), агрегации телеметрии коммутаторов и предоставления графа топологии через REST API.
-
FSM Парсер (
$O(1)$ по памяти): Реализован конечный автомат (Finite State Machine) для построчного чтения логов. Потребление оперативной памяти фиксировано и не зависит от размера загружаемого архива. -
Слой данных: Использование кодогенерации
sqlcи драйвераpgx/v5. Для вставки миллионов портов используются механизмы пакетной вставки PostgreSQL (Batch API). - Паттерн Saga (Compensation): Для максимальной скорости импорта мы отказались от глобальной SQL-транзакции. При ошибке парсинга микросервис выполняет компенсирующее действие (каскадное удаление "грязных" данных), сохраняя лог с ошибкой для клиента.
- Ленивая загрузка (Lazy Loading): Эндпоинт топологии возвращает узлы без вложенных портов для предотвращения OOM ( Out-Of-Memory) на сервере и клиенте. Данные о портах запрашиваются отдельным вызовом.
- Docker / Podman
- Make
- Установленные зависимости (выполните
make install-tools)
-
Склонируйте репозиторий и создайте конфигурационный файл из шаблона:
cp .env.example .env
-
Поднимите базу данных:
make compose-up-all
-
Запустите сервис локально (или соберите контейнер):
make run
API будет доступно по адресу http://localhost:8080.
Исчерпывающая документация находится в директории docs/:
- OpenAPI: Спецификация API доступна в
docs/api/v1/api.yaml. - Схема БД: Автоматическая документация генерируется через
tbls(см. конфиг.tbls.ymlи командуmake-gen-docs-database). - ADR: Исторический контекст принятых архитектурных решений описан в
docs/adr/. - Postman: Коллекция с настроенным окружением и тестами находится в
docs/api/v1/postman_collection.json. - cURL: Готовые примеры консольных запросов лежат в
docs/api/v1/examples/requests.sh.
| Метод | Эндпоинт | Описание |
|---|---|---|
POST |
/api/v1/parse/ |
Инициирует парсинг архива. Передается filepath. Возвращает log_id. |
GET |
/api/v1/log/{log_id} |
Проверка статуса задачи (pending, in_progress, success, error). |
GET |
/api/v1/topology/{log_id} |
Получение базового графа сети (без портов). |
GET |
/api/v1/node/{node_id} |
Получение информации по конкретному узлу. |
GET |
/api/v1/port/{node_id} |
Ленивая загрузка всех портов узла. |
GET |
/ping |
Healthcheck сервиса. |
Проект управляется через Makefile. Основные команды:
make install-tools # Установка необходимых линтеров и утилит (sqlc, migrate, tbls)
make db-gen # Генерация SQL-кода через sqlc
make gen-docs-database # Генерация документации БД в формате markdown
make lint # Запуск статического анализа (golangci-lint)
make unit-test # Запуск модульных тестов
make build # Компиляция бинарного файла в директорию bin/
make compose-up-db # Запуск только базы данных для локальной разработки
make compose-up-all # Запуск всего стека (БД, App, Мониторинг)
make build-tests # Сборка докер-образа с интеграционными тестами
make run-tests # Запуск интеграционных тестов