mirror of
https://github.com/Horizontal42/netsleuth.git
synced 2026-11-11 01:02:10 +03:00
153 lines
4.9 KiB
Markdown
153 lines
4.9 KiB
Markdown
# Руководство для контрибьюторов Netsleuth
|
||
|
||
Спасибо за интерес к проекту! Это руководство поможет вам начать вносить свой вклад.
|
||
|
||
## 🚀 Быстрый старт
|
||
|
||
### 1. Настройка окружения
|
||
|
||
```bash
|
||
# Клонируйте репозиторий
|
||
git clone https://github.com/egorovandrey/netsleuth.git
|
||
cd netsleuth
|
||
|
||
# Установите uv (если ещё не установлен)
|
||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||
|
||
# Создайте виртуальное окружение и установите зависимости
|
||
uv sync --extra tcptrace --extra ndt7
|
||
|
||
# Установите pre-commit хуки
|
||
uv run pre-commit install
|
||
```
|
||
|
||
### 2. Запуск тестов
|
||
|
||
```bash
|
||
# Все тесты
|
||
uv run pytest
|
||
|
||
# Тесты с покрытием
|
||
uv run pytest --cov=src/netsleuth --cov-report=html
|
||
|
||
# Конкретный тест
|
||
uv run pytest tests/test_exporter.py -v
|
||
```
|
||
|
||
### 3. Линтинг и форматирование
|
||
|
||
```bash
|
||
# Проверка стиля
|
||
uv run flake8 src/netsleuth
|
||
|
||
# Форматирование кода
|
||
uv run black src/netsleuth tests
|
||
|
||
# Проверка типов
|
||
uv run mypy src/netsleuth --ignore-missing-imports
|
||
```
|
||
|
||
## 📝 Как добавить новый источник геоданных
|
||
|
||
1. Создайте новый файл в `src/netsleuth/geo/` (например, `new_provider.py`)
|
||
2. Реализуйте интерфейс:
|
||
|
||
```python
|
||
from typing import Optional
|
||
from dataclasses import dataclass
|
||
|
||
@dataclass
|
||
class GeoResult:
|
||
country: Optional[str] = None
|
||
city: Optional[str] = None
|
||
asn: Optional[int] = None
|
||
org: Optional[str] = None
|
||
|
||
async def fetch_geo(ip: str) -> Optional[GeoResult]:
|
||
"""Получить геоданные для IP."""
|
||
# Ваша реализация
|
||
pass
|
||
```
|
||
|
||
3. Добавьте импорт в `src/netsleuth/geo/__init__.py`
|
||
4. Напишите тесты в `tests/test_new_provider.py`
|
||
5. Обновите документацию
|
||
|
||
## 🧪 Как написать тест для новой пробы
|
||
|
||
```python
|
||
import pytest
|
||
from unittest.mock import AsyncMock, patch
|
||
|
||
@pytest.mark.asyncio
|
||
async def test_my_probe():
|
||
# Arrange
|
||
with patch('netsleuth.my_probe.httpx.get') as mock_get:
|
||
mock_get.return_value = {"status": "ok"}
|
||
|
||
# Act
|
||
result = await run_probe("8.8.8.8")
|
||
|
||
# Assert
|
||
assert result.status == "ok"
|
||
mock_get.assert_called_once()
|
||
```
|
||
|
||
**Важно:**
|
||
- Все HTTP-запросы должны быть замокированы
|
||
- Используйте фикстуры из `tests/conftest.py`
|
||
- Добавляйте тесты на граничные случаи
|
||
|
||
## ✅ Чеклист перед Pull Request
|
||
|
||
- [ ] Код отформатирован (`black src/netsleuth tests`)
|
||
- [ ] Нет нарушений flake8 (`flake8 src/netsleuth`)
|
||
- [ ] Все тесты проходят (`pytest`)
|
||
- [ ] Покрытие не уменьшилось (минимум 60%)
|
||
- [ ] Добавлены docstrings для публичных функций
|
||
- [ ] Обновлена документация (если нужно)
|
||
- [ ] Pre-commit хуки пройдены
|
||
|
||
## 🏗️ Архитектура проекта
|
||
|
||
```
|
||
src/netsleuth/
|
||
├── cli.py # Точка входа, CLI аргументы
|
||
├── config.py # Конфигурация и настройки
|
||
├── models.py # Датаклассы для данных
|
||
├── probes/ # Модули проб (speed, latency, etc.)
|
||
├── geo/ # Геоданные и ASN lookup
|
||
├── reputation.py # Проверка по чёрным спискам
|
||
├── interpret.py # Интерпретация результатов
|
||
└── exporter.py # Экспорт в Markdown/JSON
|
||
```
|
||
|
||
Основная статья: [`ARCHITECTURE.ru.md`](ARCHITECTURE.ru.md)
|
||
|
||
## 🐛 Сообщение об ошибках
|
||
|
||
При создании issue укажите:
|
||
1. Версию Python (`python --version`)
|
||
2. Версию netsleuth (`netsleuth --version`)
|
||
3. ОС и версию
|
||
4. Команду запуска
|
||
5. Полный вывод ошибки
|
||
6. Скриншот (если применимо)
|
||
|
||
## 💡 Идеи для улучшений
|
||
|
||
Ищем помощь в следующих областях:
|
||
- [ ] Поддержка новых протоколов (QUIC, HTTP/3)
|
||
- [ ] Графический интерфейс (TUI/GUI)
|
||
- [ ] Интеграция с Prometheus/Grafana
|
||
- [ ] Поддержка IPv6-only хостов
|
||
- [ ] Локализация на другие языки
|
||
|
||
## 📞 Контакты
|
||
|
||
- GitHub Issues: [egorovandrey/netsleuth/issues](https://github.com/egorovandrey/netsleuth/issues)
|
||
- Telegram: @your_channel (если есть)
|
||
|
||
---
|
||
|
||
**Спасибо за ваш вклад!** 🎉
|