diff --git a/SRV/docs/_build/markdown/.doctrees/api/config.doctree b/SRV/docs/_build/markdown/.doctrees/api/config.doctree new file mode 100644 index 0000000..f1718f8 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/config.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/config/cors.doctree b/SRV/docs/_build/markdown/.doctrees/api/config/cors.doctree new file mode 100644 index 0000000..6612d0f Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/config/cors.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/config/init_config.doctree b/SRV/docs/_build/markdown/.doctrees/api/config/init_config.doctree new file mode 100644 index 0000000..5fc3e7b Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/config/init_config.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/config/ports.doctree b/SRV/docs/_build/markdown/.doctrees/api/config/ports.doctree new file mode 100644 index 0000000..2c9ca03 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/config/ports.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/core.doctree b/SRV/docs/_build/markdown/.doctrees/api/core.doctree new file mode 100644 index 0000000..7d26919 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/core.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/core/cli_executor.doctree b/SRV/docs/_build/markdown/.doctrees/api/core/cli_executor.doctree new file mode 100644 index 0000000..234090e Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/core/cli_executor.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/endpoints.doctree b/SRV/docs/_build/markdown/.doctrees/api/endpoints.doctree new file mode 100644 index 0000000..61c2e61 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/endpoints.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/endpoints/auth.doctree b/SRV/docs/_build/markdown/.doctrees/api/endpoints/auth.doctree new file mode 100644 index 0000000..058369f Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/endpoints/auth.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/endpoints/ip.doctree b/SRV/docs/_build/markdown/.doctrees/api/endpoints/ip.doctree new file mode 100644 index 0000000..eb55312 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/endpoints/ip.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/endpoints/network.doctree b/SRV/docs/_build/markdown/.doctrees/api/endpoints/network.doctree new file mode 100644 index 0000000..b0b711d Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/endpoints/network.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/endpoints/settings.doctree b/SRV/docs/_build/markdown/.doctrees/api/endpoints/settings.doctree new file mode 100644 index 0000000..568530a Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/endpoints/settings.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/endpoints/subnet.doctree b/SRV/docs/_build/markdown/.doctrees/api/endpoints/subnet.doctree new file mode 100644 index 0000000..5de4fd5 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/endpoints/subnet.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/endpoints/ufw.doctree b/SRV/docs/_build/markdown/.doctrees/api/endpoints/ufw.doctree new file mode 100644 index 0000000..cbc1788 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/endpoints/ufw.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/endpoints/websocket.doctree b/SRV/docs/_build/markdown/.doctrees/api/endpoints/websocket.doctree new file mode 100644 index 0000000..a9e651a Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/endpoints/websocket.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/models.doctree b/SRV/docs/_build/markdown/.doctrees/api/models.doctree new file mode 100644 index 0000000..8b7a591 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/models.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/models/auth.doctree b/SRV/docs/_build/markdown/.doctrees/api/models/auth.doctree new file mode 100644 index 0000000..01ef1fa Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/models/auth.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/models/network.doctree b/SRV/docs/_build/markdown/.doctrees/api/models/network.doctree new file mode 100644 index 0000000..cbd295e Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/models/network.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/models/request.doctree b/SRV/docs/_build/markdown/.doctrees/api/models/request.doctree new file mode 100644 index 0000000..5e2c5f5 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/models/request.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/models/subnet.doctree b/SRV/docs/_build/markdown/.doctrees/api/models/subnet.doctree new file mode 100644 index 0000000..25ca715 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/models/subnet.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/models/ufw.doctree b/SRV/docs/_build/markdown/.doctrees/api/models/ufw.doctree new file mode 100644 index 0000000..ce999f4 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/models/ufw.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/models/wifi.doctree b/SRV/docs/_build/markdown/.doctrees/api/models/wifi.doctree new file mode 100644 index 0000000..aaa7784 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/models/wifi.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/services.doctree b/SRV/docs/_build/markdown/.doctrees/api/services.doctree new file mode 100644 index 0000000..05fe385 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/services.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/services/arp_service.doctree b/SRV/docs/_build/markdown/.doctrees/api/services/arp_service.doctree new file mode 100644 index 0000000..f40a78f Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/services/arp_service.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/services/auth_service.doctree b/SRV/docs/_build/markdown/.doctrees/api/services/auth_service.doctree new file mode 100644 index 0000000..3d69920 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/services/auth_service.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/services/connect_service.doctree b/SRV/docs/_build/markdown/.doctrees/api/services/connect_service.doctree new file mode 100644 index 0000000..eb0b686 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/services/connect_service.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/services/firewalld_service.doctree b/SRV/docs/_build/markdown/.doctrees/api/services/firewalld_service.doctree new file mode 100644 index 0000000..33edddd Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/services/firewalld_service.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/services/ip_service.doctree b/SRV/docs/_build/markdown/.doctrees/api/services/ip_service.doctree new file mode 100644 index 0000000..494dd5a Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/services/ip_service.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/services/network_service.doctree b/SRV/docs/_build/markdown/.doctrees/api/services/network_service.doctree new file mode 100644 index 0000000..a7e5e82 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/services/network_service.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/services/settings_service.doctree b/SRV/docs/_build/markdown/.doctrees/api/services/settings_service.doctree new file mode 100644 index 0000000..e71df78 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/services/settings_service.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/services/subnet_service.doctree b/SRV/docs/_build/markdown/.doctrees/api/services/subnet_service.doctree new file mode 100644 index 0000000..66e9e36 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/services/subnet_service.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/services/ufw_service.doctree b/SRV/docs/_build/markdown/.doctrees/api/services/ufw_service.doctree new file mode 100644 index 0000000..eff61ba Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/services/ufw_service.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/services/wifi_service.doctree b/SRV/docs/_build/markdown/.doctrees/api/services/wifi_service.doctree new file mode 100644 index 0000000..b5bd9c9 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/services/wifi_service.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/storage.doctree b/SRV/docs/_build/markdown/.doctrees/api/storage.doctree new file mode 100644 index 0000000..6612d61 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/storage.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/storage/json_storage.doctree b/SRV/docs/_build/markdown/.doctrees/api/storage/json_storage.doctree new file mode 100644 index 0000000..b982459 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/storage/json_storage.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/storage/session_storage.doctree b/SRV/docs/_build/markdown/.doctrees/api/storage/session_storage.doctree new file mode 100644 index 0000000..d0a27cb Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/storage/session_storage.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/utils.doctree b/SRV/docs/_build/markdown/.doctrees/api/utils.doctree new file mode 100644 index 0000000..8b267dc Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/utils.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/api/utils/i18n.doctree b/SRV/docs/_build/markdown/.doctrees/api/utils/i18n.doctree new file mode 100644 index 0000000..6bacef5 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/api/utils/i18n.doctree differ diff --git a/SRV/docs/_build/markdown/.doctrees/environment.pickle b/SRV/docs/_build/markdown/.doctrees/environment.pickle new file mode 100644 index 0000000..1e96efd Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/environment.pickle differ diff --git a/SRV/docs/_build/markdown/.doctrees/index.doctree b/SRV/docs/_build/markdown/.doctrees/index.doctree new file mode 100644 index 0000000..82be9c3 Binary files /dev/null and b/SRV/docs/_build/markdown/.doctrees/index.doctree differ diff --git a/SRV/docs/_build/markdown/api/config.md b/SRV/docs/_build/markdown/api/config.md new file mode 100644 index 0000000..2a95be6 --- /dev/null +++ b/SRV/docs/_build/markdown/api/config.md @@ -0,0 +1,5 @@ +# Конфигурация + +* [config.cors](config/cors.md) +* [config.init_config](config/init_config.md) +* [config.ports](config/ports.md) diff --git a/SRV/docs/_build/markdown/api/config/cors.md b/SRV/docs/_build/markdown/api/config/cors.md new file mode 100644 index 0000000..eef216b --- /dev/null +++ b/SRV/docs/_build/markdown/api/config/cors.md @@ -0,0 +1,27 @@ +# config.cors + +Конфигурация CORS для FastAPI-приложения GONETS. + +Модуль инкапсулирует добавление middleware CORSMiddleware со списком +разрешённых источников (origins), характерных для локальной разработки и +типовых портов фронтенда (например, Vite/React на 5173/5174, dev‑серверы). + +Использование: +: cors_config = CORSMiddlewareConfig(app) + cors_config.add_cors_middleware() + +Поведение: +: - Разрешены все методы (allow_methods=[“\*”]) и заголовки (allow_headers=[“\*”]). + - Разрешены креденшлы (allow_credentials=True) для работы с куками (локаль и др.). + - При необходимости список origins можно расширить или параметризовать + на основе конфигурационного файла окружения. + +### *class* config.cors.CORSMiddlewareConfig(app: FastAPI) + +Bases: `object` + +Класс для настройки CORS политики в FastAPI + +#### add_cors_middleware() → None + +Добавляем CORS в приложение FastAPI diff --git a/SRV/docs/_build/markdown/api/config/init_config.md b/SRV/docs/_build/markdown/api/config/init_config.md new file mode 100644 index 0000000..881b670 --- /dev/null +++ b/SRV/docs/_build/markdown/api/config/init_config.md @@ -0,0 +1 @@ +# config.init_config diff --git a/SRV/docs/_build/markdown/api/config/ports.md b/SRV/docs/_build/markdown/api/config/ports.md new file mode 100644 index 0000000..c8f9809 --- /dev/null +++ b/SRV/docs/_build/markdown/api/config/ports.md @@ -0,0 +1,28 @@ +# config.ports + +### *class* config.ports.PortConfig(custom_ports: Dict[int, str] = None) + +Bases: `object` + +Конфигурация известных портов для сетевого анализа. + +Назначение: +: Предоставляет сопоставление распространённых портов с человекочитаемыми + названиями сервисов для отображения в UI и логах. Поддерживает расширение + пользовательским словарём. + +#### get_port_name(port: int) → str + +Возвращает название сервиса для указанного порта. + +* **Parameters:** + **port** – Номер порта. +* **Returns:** + Название сервиса или строка вида ‘Port-’. + +#### get_ports() → List[int] + +Возвращает список всех номеров портов. + +* **Returns:** + Список номеров портов. diff --git a/SRV/docs/_build/markdown/api/core.md b/SRV/docs/_build/markdown/api/core.md new file mode 100644 index 0000000..06015c4 --- /dev/null +++ b/SRV/docs/_build/markdown/api/core.md @@ -0,0 +1,3 @@ +# Core + +* [core.cli_executor](core/cli_executor.md) diff --git a/SRV/docs/_build/markdown/api/core/cli_executor.md b/SRV/docs/_build/markdown/api/core/cli_executor.md new file mode 100644 index 0000000..df8c657 --- /dev/null +++ b/SRV/docs/_build/markdown/api/core/cli_executor.md @@ -0,0 +1,22 @@ +# core.cli_executor + +### *class* core.cli_executor.CLIExecutor + +Bases: `object` + +Утилита для безопасного выполнения CLI‑команд. + +Назначение: +: Инкапсулирует вызов subprocess.run и приводит результат к удобному + кортежу (код возврата, stdout) без генерации исключений при ошибках. + +#### *static* run(command: list) → Tuple[int, str] + +Выполняет команду в системе и возвращает код и вывод. + +* **Parameters:** + **command** (*list*) – Список аргументов команды для выполнения. +* **Returns:** + Код возврата и вывод команды. +* **Return type:** + tuple diff --git a/SRV/docs/_build/markdown/api/endpoints.md b/SRV/docs/_build/markdown/api/endpoints.md new file mode 100644 index 0000000..966af00 --- /dev/null +++ b/SRV/docs/_build/markdown/api/endpoints.md @@ -0,0 +1,9 @@ +# API эндпоинты + +* [api.v1.auth](endpoints/auth.md) +* [api.v1.ip](endpoints/ip.md) +* [api.v1.network](endpoints/network.md) +* [api.v1.settings](endpoints/settings.md) +* [api.v1.subnet](endpoints/subnet.md) +* [api.v1.ufw](endpoints/ufw.md) +* [api.v1.websocket](endpoints/websocket.md) diff --git a/SRV/docs/_build/markdown/api/endpoints/auth.md b/SRV/docs/_build/markdown/api/endpoints/auth.md new file mode 100644 index 0000000..5a19f57 --- /dev/null +++ b/SRV/docs/_build/markdown/api/endpoints/auth.md @@ -0,0 +1,90 @@ +# api.v1.auth + +### *async* api.v1.auth.check_users_file(translations: Translations = Depends(translations_dependency)) + +Проверяет, существует ли файл users.json и содержит ли он пользователей. + +Возвращает информацию о состоянии файла и наличии пользователей. + +* **Returns:** + Словарь с ключами: + : - ”exists” (bool): Существует ли файл. + - ”has_users” (bool): Содержит ли файл пользователей. + - ”message” (str): Сообщение с описанием результата. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если произошла ошибка при проверке файла (status_code=500). + +### *async* api.v1.auth.get_current_user(request: Request, translations: Translations = Depends(translations_dependency)) + +Возвращает данные текущего пользователя и токен. + +Проверяет активную сессию по client_id и возвращает информацию о пользователе +и токен для дальнейшего использования. + +* **Parameters:** + * **request** (*Request*) – Объект запроса для получения client_id (IP-адрес клиента). + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с ключами “user” (UserResponse), “access_token” (str) и + : ”token_type” (str, всегда “bearer”). +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если сессия не найдена или истекла (status_code=401) или + произошла внутренняя ошибка (status_code=500). + +### *async* api.v1.auth.login(user: UserLogin, request: Request, translations: Translations = Depends(translations_dependency)) + +Авторизует пользователя и создаёт сессию. + +Проверяет учетные данные пользователя и возвращает токен и session_id для +последующей авторизации. + +* **Parameters:** + * **user** (*UserLogin*) – Объект с данными для входа (username, password). + * **request** (*Request*) – Объект запроса для получения client_id (IP-адрес клиента). + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Объект с access_token и session_id для авторизации. +* **Return type:** + Token +* **Raises:** + **HTTPException** – Если учетные данные неверны (status_code=401) или произошла + внутренняя ошибка (status_code=500). + +### *async* api.v1.auth.logout(request: Request, translations: Translations = Depends(translations_dependency)) + +Выход из системы, удаление сессии. + +Удаляет активную сессию пользователя по client_id. + +* **Parameters:** + * **request** (*Request*) – Объект запроса для получения client_id (IP-адрес клиента). + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Пустой словарь или сообщение об успешном выходе. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если сессия не найдена (status_code=401) или произошла + внутренняя ошибка (status_code=500). + +### *async* api.v1.auth.register(user: UserCreate, translations: Translations = Depends(translations_dependency)) + +Регистрирует нового пользователя. + +Создаёт нового пользователя на основе предоставленных данных и возвращает +информацию о зарегистрированном пользователе. + +* **Parameters:** + * **user** (*UserCreate*) – Объект с данными нового пользователя (username, password, is_admin). + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Объект с данными зарегистрированного пользователя (id, username, is_admin). +* **Return type:** + UserResponse +* **Raises:** + **HTTPException** – Если пользователь уже существует (status_code=400) или произошла + внутренняя ошибка (status_code=500). diff --git a/SRV/docs/_build/markdown/api/endpoints/ip.md b/SRV/docs/_build/markdown/api/endpoints/ip.md new file mode 100644 index 0000000..2997a1e --- /dev/null +++ b/SRV/docs/_build/markdown/api/endpoints/ip.md @@ -0,0 +1,63 @@ +# api.v1.ip + +### *async* api.v1.ip.apply_ip_config(data: Dict[str, Any] = Body(PydanticUndefined), translations: Translations = Depends(translations_dependency)) + +Применяет проверенные IP-настройки к указанному сетевому профилю. + +Обновляет настройки соединения через NetworkManager, отключает и +переподключает устройство к сети. + +* **Parameters:** + * **data** (*Dict* *[**str* *,* *Any* *]*) – Словарь с данными конфигурации, включая + “connection_id” и “ipv4_updates” с обновлениями IP-настроек. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с ключами: + : - ”success” (bool): Успешность операции. + - ”message” (str): Сообщение об успешном применении настроек. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если подключение не найдено (status_code=404) или + произошла внутренняя ошибка (status_code=500). + +### *async* api.v1.ip.check_ip_config(data: Dict[str, Any] = Body(PydanticUndefined), translations: Translations = Depends(translations_dependency)) + +Проверяет доступность IP-адреса перед его применением. + +Выполняет ARP-сканирование для проверки, занят ли указанный IP-адрес, +и возвращает результат проверки. + +* **Parameters:** + * **data** (*Dict* *[**str* *,* *Any* *]*) – Словарь с данными конфигурации, включая + “ipv4_updates” с полем “ipv4.address-data” для нового IP-адреса. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с ключами: + : - ”available” (bool): Доступен ли IP-адрес. + - ”message” (str): Сообщение о результате проверки. +* **Return type:** + Dict[str, Any] +* **Raises:** + **HTTPException** – Если произошла внутренняя ошибка (status_code=500). + +### *async* api.v1.ip.save_ip_config(data: Dict[str, Any] = Body(PydanticUndefined), translations: Translations = Depends(translations_dependency)) + +Применяет проверенные IP-настройки для отката сетевого профиля. + +Используется для сохранения и отката настроек сетевого профиля к предыдущему +состоянию через NetworkManager. + +* **Parameters:** + * **data** (*Dict* *[**str* *,* *Any* *]*) – Словарь с данными конфигурации, включая + “connection_id” и “ipv4_updates” с обновлениями IP-настроек. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с ключами: + : - ”success” (bool): Успешность операции. + - ”message” (str): Сообщение об успешном применении настроек. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если подключение не найдено (status_code=404) или + произошла внутренняя ошибка (status_code=500). diff --git a/SRV/docs/_build/markdown/api/endpoints/network.md b/SRV/docs/_build/markdown/api/endpoints/network.md new file mode 100644 index 0000000..b911246 --- /dev/null +++ b/SRV/docs/_build/markdown/api/endpoints/network.md @@ -0,0 +1,93 @@ +# api.v1.network + +### *class* api.v1.network.ContainerPositionManager + +Bases: `object` + +Класс для управления позициями и состоянием контейнеров. + +Хранит и обновляет координаты (x, y) и состояние (isOpen) для контейнеров +активации и деактивации. + +#### get_position_and_state(container_name: str, translations: Translations = Depends(translations_dependency)) → Tuple[int, int, bool] + +Получает текущие координаты и состояние указанного контейнера. + +* **Parameters:** + * **container_name** (*str*) – Имя контейнера (“activation” или “deactivation”). + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Кортеж с координатами (x, y) и состоянием (isOpen). +* **Return type:** + Tuple[int, int, bool] +* **Raises:** + **ValueError** – Если указан неверный идентификатор контейнера. + +#### update_position(container_id: int, x: int, y: int, isOpen: bool) → None + +Обновляет позицию и состояние контейнера по его идентификатору. + +* **Parameters:** + * **container_id** (*int*) – Идентификатор контейнера (1 для “activation”, 2 для “deactivation”). + * **x** (*int*) – Новая координата X. + * **y** (*int*) – Новая координата Y. + * **isOpen** (*bool*) – Новое состояние контейнера (открыт/закрыт). +* **Raises:** + **ValueError** – Если container_id не соответствует ни одному контейнеру. + +### *async* api.v1.network.get_hostname(translations: Translations = Depends(translations_dependency)) + +Возвращает имя хоста системы. + +Выполняет запрос к сервису для получения имени хоста. + +* **Parameters:** + **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с ключом “hostname” и значением имени хоста. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если произошла ошибка при получении имени хоста (status_code=500). + +### *async* api.v1.network.get_network_data(translations: Translations = Depends(translations_dependency)) → Dict[str, Dict] + +Возвращает текущие сетевые данные в виде словаря. + +Получает данные о сетевых интерфейсах, разделяет их на активные и неактивные, +и возвращает их в формате Activation и Deactivation с учётом позиций и состояний +контейнеров. + +* **Parameters:** + **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с ключами “activation” и “deactivation”, содержащими + : данные о соответствующих контейнерах. +* **Return type:** + Dict[str, Dict] +* **Raises:** + **HTTPException** – Если произошла ошибка при получении данных (status_code=500). + +### *async* api.v1.network.update_container_position(data: Dict[str, int | bool] = Body(PydanticUndefined), translations: Translations = Depends(translations_dependency)) + +Обновляет позицию и состояние контейнера. + +Принимает данные о новом положении и состоянии контейнера и обновляет их +в менеджере позиций. + +* **Parameters:** + * **data** (*Dict* *[**str* *,* *Union* *[**int* *,* *bool* *]* *]*) – Словарь с ключами: + - “container_id” (int): Идентификатор контейнера (1 или 2). + - “container_x” (int): Новая координата X. + - “container_y” (int): Новая координата Y. + - “isOpen” (bool): Новое состояние контейнера (открыт/закрыт). + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с ключами: + : - ”success” (bool): Успешность операции. + - ”message” (str): Сообщение об успешном обновлении. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если отсутствуют обязательные поля (status_code=400) или + типы данных неверны. diff --git a/SRV/docs/_build/markdown/api/endpoints/settings.md b/SRV/docs/_build/markdown/api/endpoints/settings.md new file mode 100644 index 0000000..a892d4a --- /dev/null +++ b/SRV/docs/_build/markdown/api/endpoints/settings.md @@ -0,0 +1,104 @@ +# api.v1.settings + +### api.v1.settings.clear_all_data(translations: Translations = Depends(translations_dependency)) + +Очищает данные узлов подсети и точек доступа Wi-Fi в обоих файлах. + +Удаляет все записи из devices.json и wifi.json. + +* **Parameters:** + **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с сообщением об успешной очистке. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если произошла ошибка очистки (status_code=500). + +### api.v1.settings.clear_subnet(subnet: str | None = None, translations: Translations = Depends(translations_dependency)) + +Очищает данные узлов подсети, сохранённые в devices.json. + +Удаляет все записи об узлах подсети, оставляя файл пустым. + +* **Parameters:** + * **subnet** (*Optional* *[**str* *]*) – Подсеть в формате CIDR (например, “10.1.1.0/24”). + Если None, очищает все подсети. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с сообщением об успешной очистке. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если произошла ошибка очистки (status_code=500). + +### api.v1.settings.clear_wifi(translations: Translations = Depends(translations_dependency)) + +Очищает данные точек доступа Wi-Fi, сохранённые в wifi.json. + +Удаляет все записи о точках доступа, оставляя файл пустым. + +* **Parameters:** + **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с сообщением об успешной очистке. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если произошла ошибка очистки (status_code=500). + +### *async* api.v1.settings.export_devices(request: SubnetScanRequest = Body(PydanticUndefined), translations: Translations = Depends(translations_dependency)) + +Экспортирует файл с данными устройств в формате JSON для указанной подсети. + +* **Parameters:** + * **request** (*SubnetScanRequest*) – Объект с полем subnet в формате CIDR. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Файл .json для скачивания. +* **Return type:** + FileResponse +* **Raises:** + **HTTPException** – Если файл не найден (status_code=404). + +### *async* api.v1.settings.export_wifi(translations: Translations = Depends(translations_dependency)) + +Экспортирует файл с данными устройств в формате JSON. + +* **Parameters:** + **translations** – Объект переводов для текущего языка. +* **Returns:** + Файл wifi.json для скачивания. +* **Return type:** + FileResponse +* **Raises:** + **HTTPException** – Если файл не найден (status_code=404). + +### *async* api.v1.settings.get_system_language(request: Request, translations: Translations = Depends(translations_dependency)) + +Выводит текущий язык, установленный в системе на основе locale. + +Выполняет команду ‘locale’ в системе и извлекает параметры LANG + +* **Parameters:** + * **request** (*Request*) – Объект запроса для доступа к параметрам. + * **translations** – Объект переводов текущего языка. +* **Returns:** + Словарь с текущим языком системы. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если не удалось извлечь системный язык (status_code=500). + +### api.v1.settings.set_language(locale: str, response: Response, translations: Translations = Depends(translations_dependency)) + +Устанавливает куку locale для смены языка пользователя. + +* **Parameters:** + * **locale** (*str*) – Используемый язык. + * **response** (*Response*) – Запрос. + * **translations** – Объект переводов текущего языка. +* **Returns:** + Сообщение об успешной установке языка. +* **Return type:** + dict diff --git a/SRV/docs/_build/markdown/api/endpoints/subnet.md b/SRV/docs/_build/markdown/api/endpoints/subnet.md new file mode 100644 index 0000000..cae5698 --- /dev/null +++ b/SRV/docs/_build/markdown/api/endpoints/subnet.md @@ -0,0 +1,193 @@ +# api.v1.subnet + +### api.v1.subnet.add_note(mac: str, request: NoteRequest, subnet_service: SubnetService = Depends(get_subnet_service), translations: Translations = Depends(translations_dependency)) + +Добавляет заметку для устройства по MAC-адресу. + +Привязывает заметку к устройству, идентифицируемому по MAC-адресу. + +* **Parameters:** + * **mac** (*str*) – MAC-адрес устройства. + * **request** (*NoteRequest*) – Объект с полем “note” для текста заметки. + * **subnet_service** – Сервис сканирования подсети. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с сообщением об успешном добавлении заметки. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если устройство не найдено (status_code=404), заметка уже + существует (status_code=400), или произошла внутренняя ошибка (status_code=500). + +### api.v1.subnet.add_wifi_note(ssid: str, request: NoteRequest, translations: Translations = Depends(translations_dependency)) + +Добавляет заметку для сети Wi-Fi по SSID. + +Привязывает заметку к Wi-Fi сети, идентифицируемой по SSID. + +* **Parameters:** + * **ssid** (*str*) – Идентификатор Wi-Fi сети. + * **request** (*NoteRequest*) – Объект с полем “note” для текста заметки. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с сообщением об успешном добавлении заметки. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если сеть не найдена (status_code=404), заметка уже + существует (status_code=400), или произошла внутренняя ошибка (status_code=500). + +### api.v1.subnet.connect_to_wifi(request: WifiConnectRequest, translations: Translations = Depends(translations_dependency)) + +Подключается к Wi-Fi сети по SSID и паролю. + +Выполняет подключение к указанной Wi-Fi сети с использованием предоставленных +учетных данных. + +* **Parameters:** + * **request** (*WifiConnectRequest*) – Объект с полями “ssid” и “password”. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с сообщением об успешном подключении. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если подключение не удалось (status_code=400). + +### api.v1.subnet.delete_note(mac: str, subnet_service: SubnetService = Depends(get_subnet_service), translations: Translations = Depends(translations_dependency)) + +Удаляет заметку для устройства по MAC-адресу. + +Удаляет привязанную заметку для указанного устройства. + +* **Parameters:** + * **mac** (*str*) – MAC-адрес устройства. + * **subnet_service** – Сервис сканирования подсети. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с сообщением об успешном удалении заметки. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если устройство не найдено (status_code=404), заметка не + существует (status_code=400), или произошла внутренняя ошибка (status_code=500). + +### api.v1.subnet.delete_wifi_note(ssid: str, translations: Translations = Depends(translations_dependency)) + +Удаляет заметку для сети Wi-Fi по SSID. + +Удаляет привязанную заметку для указанной Wi-Fi сети. + +* **Parameters:** + * **ssid** (*str*) – Идентификатор Wi-Fi сети. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с сообщением об успешном удалении заметки. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если сеть не найдена (status_code=404), заметка не + существует (status_code=400), или произошла внутренняя ошибка (status_code=500). + +### api.v1.subnet.disconnect_from_wifi(request: WifiDisconnectRequest, translations: Translations = Depends(translations_dependency)) + +Отключается от Wi-Fi сети по указанному SSID. + +Выполняет отключение от указанной Wi-Fi сети. + +* **Parameters:** + * **request** (*WifiDisconnectRequest*) – Объект с полем “ssid”. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с сообщением об успешном отключении. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если отключение не удалось (status_code=400). + +### api.v1.subnet.get_wifi_status(translations: Translations = Depends(translations_dependency)) + +Проверяет статус текущего подключения к Wi-Fi. + +Возвращает информацию о текущем состоянии подключения и SSID, если подключение активно. + +* **Parameters:** + **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с ключами: + : - ”status” (str): Состояние (“connected” или другое). + - ”ssid” (str, optional): SSID текущей сети, если подключено. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если проверка статуса не удалась (status_code=400). + +### api.v1.subnet.scan_subnet(request: SubnetScanRequest = Body(PydanticUndefined), subnet_service: SubnetService = Depends(get_subnet_service), translations: Translations = Depends(translations_dependency)) + +Сканирует локальную подсеть и возвращает данные об устройствах. + +Выполняет сканирование указанной подсети для обнаружения активных устройств. + +* **Parameters:** + * **request** (*SubnetScanRequest*) – Объект с полем subnet. + * **subnet_service** – Сервис сканирования подсети. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Объект с результатами сканирования (устройства и их данные). +* **Return type:** + SubnetScanResult +* **Raises:** + **HTTPException** – Если произошла ошибка сканирования (status_code=500). + +### api.v1.subnet.scan_wifi(timeout: int = 30, translations: Translations = Depends(translations_dependency)) + +Сканирует Wi-Fi точки доступа и возвращает данные о них. + +Выполняет сканирование доступных Wi-Fi сетей с указанным таймаутом. + +* **Parameters:** + * **timeout** (*int* *,* *optional*) – Таймаут сканирования в секундах. По умолчанию 30. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Объект с результатами сканирования (список Wi-Fi сетей). +* **Return type:** + WifiScanResult +* **Raises:** + **HTTPException** – Если произошла ошибка сканирования Wi-Fi (status_code=500). + +### api.v1.subnet.update_note(mac: str, request: NoteRequest, subnet_service: SubnetService = Depends(get_subnet_service), translations: Translations = Depends(translations_dependency)) + +Обновляет заметку для устройства по MAC-адресу. + +Изменяет существующую заметку, привязанную к устройству. + +* **Parameters:** + * **mac** (*str*) – MAC-адрес устройства. + * **request** (*NoteRequest*) – Объект с полем “note” для нового текста заметки. + * **subnet_service** – Сервис сканирования подсети. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с сообщением об успешном обновлении заметки. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если устройство не найдено (status_code=404), заметка не + существует (status_code=400), или произошла внутренняя ошибка (status_code=500). + +### api.v1.subnet.update_wifi_note(ssid: str, request: NoteRequest, translations: Translations = Depends(translations_dependency)) + +Обновляет заметку для сети Wi-Fi по SSID. + +Изменяет существующую заметку, привязанную к Wi-Fi сети. + +* **Parameters:** + * **ssid** (*str*) – Идентификатор Wi-Fi сети. + * **request** (*NoteRequest*) – Объект с полем “note” для нового текста заметки. + * **translations** – Объект переводов для текущего языка. +* **Returns:** + Словарь с сообщением об успешном обновлении заметки. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если сеть не найдена (status_code=404), заметка не + существует (status_code=400), или произошла внутренняя ошибка (status_code=500). diff --git a/SRV/docs/_build/markdown/api/endpoints/ufw.md b/SRV/docs/_build/markdown/api/endpoints/ufw.md new file mode 100644 index 0000000..52fa536 --- /dev/null +++ b/SRV/docs/_build/markdown/api/endpoints/ufw.md @@ -0,0 +1,104 @@ +# api.v1.ufw + +### *class* api.v1.ufw.RuleNumbers(, numbers: List[int]) + +Bases: `BaseModel` + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### numbers *: List[int]* + +### *async* api.v1.ufw.add_ufw_in_rules(rules: List[UFWRule]) + +Добавляет входящие (in) правила UFW. + +* **Parameters:** + **rules** (*List* *[**UFWRule* *]*) – Список правил, определяющих направления, + порты/диапазоны/протоколы и действия (allow/deny/reject). +* **Returns:** + Итог выполнения с количеством успешно добавленных правил и деталями + по каждому правилу. +* **Return type:** + dict +* **Raises:** + * **HTTPException** – Если UFW отключен (status_code=400) или при внутренних + * **ошибках** **(****status_code=500****)****.** – + +### *async* api.v1.ufw.add_ufw_out_rules(rules: List[UFWRule]) + +Добавляет исходящие (out) правила UFW. + +* **Parameters:** + **rules** (*List* *[**UFWRule* *]*) – Список правил исходящего трафика для добавления. +* **Returns:** + Объект статуса с сообщением об успешном добавлении. +* **Return type:** + dict +* **Raises:** + * **HTTPException** – Если UFW отключен (status_code=400) или при внутренних + * **ошибках** **(****status_code=500****)****.** – + +### *async* api.v1.ufw.delete_ufw_rules(rule_numbers: RuleNumbers) + +Удаляет правила UFW по их номерам. + +* **Parameters:** + **rule_numbers** (*RuleNumbers*) – Номера правил, подлежащих удалению (как в + выводе ufw status numbered). +* **Returns:** + Информация об общем количестве удаляемых правил, числе успешных и + возможной ошибке. +* **Return type:** + dict +* **Raises:** + **HTTPException** – При ошибках удаления (status_code=500). + +### *async* api.v1.ufw.disable_ufw() + +Выключает UFW. + +* **Returns:** + Словарь с ключами status и message при успешном выполнении. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если выключение завершилось неуспешно (status_code=500). + +### *async* api.v1.ufw.enable_ufw() + +Включает UFW. + +* **Returns:** + Словарь с ключами status и message при успешном выполнении. +* **Return type:** + dict +* **Raises:** + **HTTPException** – Если включение завершилось неуспешно (status_code=500). + +### *async* api.v1.ufw.get_ufw_rules() + +Возвращает все правила UFW. + +Осуществляет обращение к сервису UFWService для чтения текущего списка +правил брандмауэра и возвращает результат в сериализованном виде для клиента. + +* **Returns:** + Структура с коллекцией правил и сопутствующей + информацией о состоянии. +* **Return type:** + UFWRulesResponse +* **Raises:** + **HTTPException** – В случае ошибок взаимодействия с UFW (status_code=500). + +### *async* api.v1.ufw.get_ufw_status() + +Возвращает текущий статус UFW. + +* **Returns:** + Объект со сведениями о включенности UFW и деталями статуса. +* **Return type:** + UFWStatus +* **Raises:** + **HTTPException** – Если не удалось получить статус (status_code=500). diff --git a/SRV/docs/_build/markdown/api/endpoints/websocket.md b/SRV/docs/_build/markdown/api/endpoints/websocket.md new file mode 100644 index 0000000..2e0e595 --- /dev/null +++ b/SRV/docs/_build/markdown/api/endpoints/websocket.md @@ -0,0 +1,78 @@ +# api.v1.websocket + +### *class* api.v1.websocket.WebSocketManager + +Bases: `object` + +Класс для управления подключениями к WebSocket-серверу. + +Обрабатывает подключение, отключение и трансляцию сообщений для клиентов, +подключённых через WebSocket. + +#### *async* broadcast(message: dict) + +Транслирует сообщения всем подключённым клиентам. + +Отправляет JSON-данные всем активным соединениям, обрабатывая +отключения клиентов. + +* **Parameters:** + **message** (*dict*) – Сообщение для трансляции в формате JSON. +* **Raises:** + * **WebSocketDisconnect** – Если клиент неожиданно отключился. + * **Exception** – Если произошла другая ошибка при отправке. + +#### *async* connect(websocket: WebSocket) + +Подключает клиента к WebSocket-серверу. + +Принимает подключение и добавляет WebSocket в список активных соединений. + +* **Parameters:** + **websocket** (*WebSocket*) – Объект WebSocket для подключения. +* **Raises:** + **Exception** – Если произошла ошибка при принятии подключения. + +#### disconnect(websocket: WebSocket) + +Отключает клиента от WebSocket-серверу. + +Удаляет WebSocket из списка активных соединений. + +* **Parameters:** + **websocket** (*WebSocket*) – Объект WebSocket для отключения. + +### *async* api.v1.websocket.broadcast_data(translations: Translations = Depends(translations_dependency)) + +Таск для периодической трансляции сетевых данных. + +Выполняет сканирование сети и отправляет данные всем подключённым клиентам +с интервалом в 2 секунды. + +* **Parameters:** + **translations** – Объект переводов для текущего языка. +* **Raises:** + **Exception** – Если произошла ошибка при получении данных или трансляции. + +### *async* api.v1.websocket.startup_event() + +Запуск таска для трансляции сетевых данных при старте приложения. + +Создаёт асинхронную задачу для периодической трансляции данных. + +* **Raises:** + **Exception** – Если произошла ошибка при запуске таска. + +### *async* api.v1.websocket.websocket_endpoint(websocket: WebSocket, translations: Translations = Depends(translations_dependency)) + +Обработчик WebSocket-соединения. + +Управляет соединением клиента, принимает данные для обновления позиций +контейнеров и транслирует сетевые данные. + +* **Parameters:** + * **websocket** (*WebSocket*) – Объект WebSocket для обработки соединения. + * **translations** – Объект переводов для текущего языка. +* **Raises:** + * **WebSocketDisconnect** – Если клиент отключился. + * **Exception** – Если произошла ошибка при обработке данных. diff --git a/SRV/docs/_build/markdown/api/models.md b/SRV/docs/_build/markdown/api/models.md new file mode 100644 index 0000000..9333fab --- /dev/null +++ b/SRV/docs/_build/markdown/api/models.md @@ -0,0 +1,8 @@ +# Модели + +* [models.auth](models/auth.md) +* [models.network](models/network.md) +* [models.request](models/request.md) +* [models.subnet](models/subnet.md) +* [models.ufw](models/ufw.md) +* [models.wifi](models/wifi.md) diff --git a/SRV/docs/_build/markdown/api/models/auth.md b/SRV/docs/_build/markdown/api/models/auth.md new file mode 100644 index 0000000..fa1f1e1 --- /dev/null +++ b/SRV/docs/_build/markdown/api/models/auth.md @@ -0,0 +1,85 @@ +# models.auth + +### *class* models.auth.Token(, access_token: str, token_type: str, session_id: str | None = None, user: UserResponse | None = None) + +Bases: `BaseModel` + +Токен пользователя + +Атрибуты: +: access_token (str): Токен пользователя (захэширован) + token_type (str): Тип токена + session_id (Optional[str]): Идентификатор сессии + user (Optional[UserResponse]): Пользователь на основе проверки наличия пользователя + +#### access_token *: str* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### session_id *: str | None* + +#### token_type *: str* + +#### user *: UserResponse | None* + +### *class* models.auth.UserCreate(, username: str, password: str, is_admin: bool = False) + +Bases: `BaseModel` + +Модель созданного пользователя + +Атрибуты: +: username (str): Имя пользователя + password (str): Пароль пользователя + is_admin (bool): Административный доступ + +#### is_admin *: bool* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### password *: str* + +#### username *: str* + +### *class* models.auth.UserLogin(, username: str, password: str) + +Bases: `BaseModel` + +Модель авторизации пользователя + +Атрибуты: +: username (str): Имя пользователя + password (str): Пароль пользователя + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### password *: str* + +#### username *: str* + +### *class* models.auth.UserResponse(, id: int, username: str, is_admin: bool) + +Bases: `BaseModel` + +Модель проверки наличия пользователя + +Атрибуты: +: id (int): Идентификатор + username (str): Имя пользователя + is_admin (bool): Административный доступ + +#### id *: int* + +#### is_admin *: bool* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### username *: str* diff --git a/SRV/docs/_build/markdown/api/models/network.md b/SRV/docs/_build/markdown/api/models/network.md new file mode 100644 index 0000000..a8ef200 --- /dev/null +++ b/SRV/docs/_build/markdown/api/models/network.md @@ -0,0 +1,238 @@ +# models.network + +### *class* models.network.Activation(, id: int, interfaces: List[NetworkInterface | WiFiDevice], container_x: int, container_y: int, isOpen: bool = True) + +Bases: `BaseModel` + +Модель активированных интерфейсов + +Атрибуты: +: id (int): Идентификатор ноды активированных интерфейсов + interfaces (List[Union[NetworkInterface, WiFiDevice]]): Активированные интерфейсы + container_x (int): Положение по X на холсте + container_y (int): Положение по Y на холсте + isOpen (bool): Флаг скрытия ноды на холсте + +#### container_x *: int* + +#### container_y *: int* + +#### id *: int* + +#### interfaces *: List[NetworkInterface | WiFiDevice]* + +#### isOpen *: bool* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +### *class* models.network.Deactivation(, id: int, interfaces: List[NetworkInterface | WiFiDevice], container_x: int, container_y: int, isOpen: bool = True) + +Bases: `BaseModel` + +Модель отключенных интерфейсов + +Атрибуты: +: id (int): Идентификатор ноды отключенных интерфейсов + interfaces (List[Union[NetworkInterface, WiFiDevice]]): Отключенные интерфейсы + container_x (int): Положение по X на холсте + container_y (int): Положение по Y на холсте + isOpen (bool): Флаг скрытия ноды на холсте + +#### container_x *: int* + +#### container_y *: int* + +#### id *: int* + +#### interfaces *: List[NetworkInterface | WiFiDevice]* + +#### isOpen *: bool* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +### *class* models.network.IPConfig(, configurations: List[IndividualIPConfig]) + +Bases: `BaseModel` + +Модель конфигурации IP (IPv4/IPv6) + +Атрибуты: +: configurations (List[IndividualIPConfig]): Список индивидуальных IP-конфигураций + +#### configurations *: List[IndividualIPConfig]* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +### *class* models.network.IPv4Route(, destination: str, prefix: int, next_hop: str, metric: int) + +Bases: `BaseModel` + +Модель маршрута IPv4 + +Атрибуты: +: destination (str): IP-адрес назначения + prefix (int): Префикс подсети в формате CIDR + next_hop (str): Адрес следующего узла (маршрутизатор) + metric (int): Метрика маршрута + +#### destination *: str* + +#### metric *: int* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### next_hop *: str* + +#### prefix *: int* + +### *class* models.network.IPv6Route(, destination: str, prefix: int, next_hop: str, metric: int) + +Bases: `BaseModel` + +Модель маршрута IPv6 + +Атрибуты: +: destination (str): IP-адрес назначения + prefix (int): Префикс подсети (CIDR) + next_hop (str): Адрес следующего узла (маршрутизатор) + metric (int): Метрика маршрута + +#### destination *: str* + +#### metric *: int* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### next_hop *: str* + +#### prefix *: int* + +### *class* models.network.IndividualIPConfig(, address: str, routes: List[IPv4Route | IPv6Route], method: str | None, gateway: str, dns: List[str]) + +Bases: `BaseModel` + +Модель индивидуальной конфигурации IP-адреса + +Атрибуты: +: address (str): IP-адрес интерфейса + routes (List[Union[IPv4Route, IPv6Route]]): Список маршрутов (IPv4/IPv6) + method (Optional[str]): Метод назначения IP + gateway (str): Основной шлюз по умолчанию + dns (List[str]): Список DNS-серверов + +#### address *: str* + +#### dns *: List[str]* + +#### gateway *: str* + +#### method *: str | None* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### routes *: List[IPv4Route | IPv6Route]* + +### *class* models.network.NetworkInterface(, name: str, type: str, mac_address: str, device_state: str, active_connection: str, device_mtu: str, ipv4: IPConfig, ipv6: IPConfig, container_x: int = 0, container_y: int = 0) + +Bases: `BaseModel` + +Модель базового сетевого интерфейса + +Атрибуты: +: name (str): Название интерфейса + type (str): Тип интерфейса + mac_address (str): MAC-адрес устройства + device_state (str): Состояние устройства + active_connection (str): Название активного соединения + device_mtu (str): MTU устройства + ipv4 (IPConfig): Конфигурация IPv4 + ipv6 (IPConfig): Конфигурация IPv6 + container_x (int): Положение по X на холсте + container_y (int): Положение по Y на холсте + +#### active_connection *: str* + +#### container_x *: int* + +#### container_y *: int* + +#### device_mtu *: str* + +#### device_state *: str* + +#### ipv4 *: IPConfig* + +#### ipv6 *: IPConfig* + +#### mac_address *: str* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### name *: str* + +#### type *: str* + +### *class* models.network.NetworkInterfacesContainer(, interfaces: List[NetworkInterface | WiFiDevice], container_x: int, container_y: int) + +Bases: `BaseModel` + +Контейнер для группы сетевых интерфейсов с координатами + +Атрибуты: +: interfaces (List[Union[NetworkInterface, WiFiDevice]]): Список интерфейсов + container_x (int): Положение по оси X + container_y (int): Положение по оси Y + +#### container_x *: int* + +#### container_y *: int* + +#### interfaces *: List[NetworkInterface | WiFiDevice]* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +### *class* models.network.WiFiDevice(, name: str, type: str, mac_address: str, device_state: str, active_connection: str, device_mtu: str, ipv4: IPConfig, ipv6: IPConfig, container_x: int = 0, container_y: int = 0, ssid: str | None = None, bssid: str | None = None, bitrate: int | None = None, strength: int | None = None, frequency: float | None = None, mode: str | int = None) + +Bases: `NetworkInterface` + +Модель Wi-Fi устройства (наследуется от NetworkInterface) + +Атрибуты: +: ssid (Optional[str]): Название Wi-Fi сети + bssid (Optional[str]): MAC-адрес точки доступа + bitrate (Optional[int]): Скорость соединения + strength (Optional[int]): Уровень сигнала + frequency (Optional[float]): Частота + mode (Union[str, int]): Режим работы + +#### bitrate *: int | None* + +#### bssid *: str | None* + +#### frequency *: float | None* + +#### mode *: str | int* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### ssid *: str | None* + +#### strength *: int | None* diff --git a/SRV/docs/_build/markdown/api/models/request.md b/SRV/docs/_build/markdown/api/models/request.md new file mode 100644 index 0000000..90e9223 --- /dev/null +++ b/SRV/docs/_build/markdown/api/models/request.md @@ -0,0 +1,49 @@ +# models.request + +### *class* models.request.NoteRequest(, note: str) + +Bases: `BaseModel` + +Модель добавления заметки к просканированному устройству + +Атрибуты: +: note (str): Заметка устройства + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### note *: str* + +### *class* models.request.WifiConnectRequest(, ssid: str, password: str) + +Bases: `BaseModel` + +Модель для подключения к точке доступа Wi-Fi + +Атрибуты: +: ssid (str): Название точки доступа Wi-Fi + password (str): Пароль точки доступа Wi-Fi + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### password *: str* + +#### ssid *: str* + +### *class* models.request.WifiDisconnectRequest(, ssid: str) + +Bases: `BaseModel` + +Модель для отключения от точки доступа Wi-Fi + +Атрибуты: +: ssid (str): Название точки доступа Wi-Fi + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### ssid *: str* diff --git a/SRV/docs/_build/markdown/api/models/subnet.md b/SRV/docs/_build/markdown/api/models/subnet.md new file mode 100644 index 0000000..49ca2ab --- /dev/null +++ b/SRV/docs/_build/markdown/api/models/subnet.md @@ -0,0 +1,70 @@ +# models.subnet + +### *class* models.subnet.Device(, ip: str, mac: str | None = None, hostname: str | None = None, vendor: str | None = None, open_ports: List[str] = [], status: str, last_seen: str | None = None, note: str | None = None) + +Bases: `BaseModel` + +Сканируемое устройство в подсети + +Атрибуты: +: ip (str): IP-адрес устройства + mac (Optional[str]): MAC-адрес устройства + hostname (Optional[str]): Имя хоста + vendor (Optional[str]): Название производителя устройства (По MAC-адресу) + open_ports (List[str]): Открытые порты устройства + status (str): Статус устройства (онлайн/оффлайн) + last_seen (Optional[str]): Последняя активность устройства + note (Optional[str]): Заметка устройства + +#### hostname *: str | None* + +#### ip *: str* + +#### last_seen *: str | None* + +#### mac *: str | None* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### note *: str | None* + +#### open_ports *: List[str]* + +#### status *: str* + +#### vendor *: str | None* + +### *class* models.subnet.SubnetScanRequest(, subnet: str | None = None) + +Bases: `BaseModel` + +Параметры для сканирования подсети + +Атрибуты: +: subnet (Optional[str]): Подсеть для сканирования (например 192.168.1.0/24), опционально + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### subnet *: str | None* + +### *class* models.subnet.SubnetScanResult(, devices: List[Device] = [], error: str | None = None) + +Bases: `BaseModel` + +Результат сканирования устройств в подсети + +Атрибуты: +: devices (List[Device]): Список просканированных устройств + error (Optional[str]): Сообщение об ошибке, если сканирование не удалось + +#### devices *: List[Device]* + +#### error *: str | None* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. diff --git a/SRV/docs/_build/markdown/api/models/ufw.md b/SRV/docs/_build/markdown/api/models/ufw.md new file mode 100644 index 0000000..d4074ee --- /dev/null +++ b/SRV/docs/_build/markdown/api/models/ufw.md @@ -0,0 +1,195 @@ +# models.ufw + +### *class* models.ufw.Action(\*values) + +Bases: `str`, `Enum` + +Enum для действий UFW. + +#### ALLOW + +Разрешить трафик + +#### DENY + +Запретить трафик без уведомления + +#### REJECT + +Запретить трафик с уведомлением отправителю + +#### ALLOW *= 'allow'* + +#### DENY *= 'deny'* + +#### REJECT *= 'reject'* + +### *class* models.ufw.Direction(\*values) + +Bases: `str`, `Enum` + +Enum для направления трафика UFW. + +#### IN + +Входящий трафик + +#### OUT + +Исходящий трафик + +#### IN *= 'in'* + +#### OUT *= 'out'* + +### *class* models.ufw.Protocol(\*values) + +Bases: `str`, `Enum` + +Enum для сетевых протоколов UFW. + +#### BOTH *= 'both'* + +#### TCP *= 'tcp'* + +#### UDP *= 'udp'* + +#### *property* protocols *: List[str]* + +Возвращает список протоколов для использования в команде UFW. + +### *class* models.ufw.UFWRule(, action: Action, direction: Direction, from_ip: str, to_ip: str, port: int | str, protocol: Protocol, comment: str | None = None) + +Bases: `BaseModel` + +Модель правила UFW + +#### action *: Action* + +#### comment *: str | None* + +#### direction *: Direction* + +#### from_ip *: str* + +#### *classmethod* from_ufw_output(line: str) → UFWRule + +Создает экземпляр UFWRule из строки вывода команды ‘ufw status numbered’. + +* **Parameters:** + **line** – Строка вывода UFW (например, “[1] 80/tcp ALLOW IN 192.168.1.0/24 # Web Server”) +* **Returns:** + Новый экземпляр правила +* **Return type:** + UFWRule + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### port *: int | str* + +#### protocol *: Protocol* + +#### to_ip *: str* + +#### to_ufw_command() → str + +Преобразует правило в команду UFW. + +#### *classmethod* validate_action(v) + +Приводит значение action к нижнему регистру перед валидацией + +#### *classmethod* validate_ip(v) + +Проверяет корректность IP адреса + +#### *classmethod* validate_ip_version_compatibility(v, values) + +Проверяет совместимость версий IP адресов + +#### *classmethod* validate_port(v) + +Проверяет корректность порта или диапазона портов. + +* **Parameters:** + **v** – Порт (число) или диапазон портов (строка вида “3000:3999”) +* **Returns:** + Валидированное значение порта +* **Return type:** + Union[int, str] +* **Raises:** + **ValueError** – Если порт или диапазон портов некорректен + +#### *classmethod* validate_protocol(v) + +Приводит значение protocol к нижнему регистру перед валидацией + +### *class* models.ufw.UFWRulesResponse(\*, enabled: bool, rules: ~typing.List[~models.ufw.UFWRule] = ) + +Bases: `BaseModel` + +Модель для представления списка правил UFW. + +#### enabled + +Включен ли UFW + +* **Type:** + bool + +#### rules + +Список правил UFW + +* **Type:** + List[models.ufw.UFWRule] + +#### total_rules + +Общее количество правил + +#### enabled *: bool* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### rules *: List[UFWRule]* + +#### *property* total_rules *: int* + +Возвращает общее количество правил. + +### *class* models.ufw.UFWStatus(, enabled: bool, message: str) + +Bases: `BaseModel` + +Модель для представления статуса UFW. + +#### enabled + +Включен ли UFW + +* **Type:** + bool + +#### message + +Сообщение о статусе + +* **Type:** + str + +#### last_checked + +Время последней проверки статуса + +#### enabled *: bool* + +#### message *: str* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. diff --git a/SRV/docs/_build/markdown/api/models/wifi.md b/SRV/docs/_build/markdown/api/models/wifi.md new file mode 100644 index 0000000..d227e7c --- /dev/null +++ b/SRV/docs/_build/markdown/api/models/wifi.md @@ -0,0 +1,55 @@ +# models.wifi + +### *class* models.wifi.WifiAccessPoint(, ssid: str | None = None, bssid: str, channel: int | None = None, signal: int | None = None, encryption: str | None = None, frequency: str | None = None, vendor: str | None = None, hidden: bool = False, note: str | None = None) + +Bases: `BaseModel` + +Модель точки доступа Wi-Fi + +Атрибуты: +: ssid (Optional[str]): Название точки доступа. Может быть скрытым + bssid (str): Уникальный идентификатор точки доступа (по типу MAC-адреса) + channel (Optional[int]): Канал, на котором работает точка доступа + signal (Optional[int]): Уровень сигнала (dBm) + encryption (Optional[str]): Тип шифрования (WPA2, WPA3, открытая и т.д.) + frequency (Optional[str]): Частота вещания (2.4GHz/5GHz) + vendor (Optional[str]): Производитель точки доступа (определяется по MAC-адресу) + hidden (bool): Флаг скрытия названия точки доступа (ssid) + note (Optional[str]): Заметка для точки доступа + +#### bssid *: str* + +#### channel *: int | None* + +#### encryption *: str | None* + +#### frequency *: str | None* + +#### hidden *: bool* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. + +#### note *: str | None* + +#### signal *: int | None* + +#### ssid *: str | None* + +#### vendor *: str | None* + +### *class* models.wifi.WifiScanResult(, access_points: List[WifiAccessPoint]) + +Bases: `BaseModel` + +Результат сканирования Wi-Fi + +Атрибуты: +: access_points (List[WifiAccessPoint]): Список найденных Wi-Fi точек доступа + +#### access_points *: List[WifiAccessPoint]* + +#### model_config *: ClassVar[ConfigDict]* *= {}* + +Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict]. diff --git a/SRV/docs/_build/markdown/api/services.md b/SRV/docs/_build/markdown/api/services.md new file mode 100644 index 0000000..c3797c0 --- /dev/null +++ b/SRV/docs/_build/markdown/api/services.md @@ -0,0 +1,12 @@ +# Сервисы + +* [ARP Service](services/arp_service.md) +* [Auth Service](services/auth_service.md) +* [Connect Service](services/connect_service.md) +* [Firewalld Service](services/firewalld_service.md) +* [IP Service](services/ip_service.md) +* [Network Service](services/network_service.md) +* [Settings Service](services/settings_service.md) +* [Subnet Service](services/subnet_service.md) +* [UFW Service](services/ufw_service.md) +* [Wifi Service](services/wifi_service.md) diff --git a/SRV/docs/_build/markdown/api/services/arp_service.md b/SRV/docs/_build/markdown/api/services/arp_service.md new file mode 100644 index 0000000..609b0b7 --- /dev/null +++ b/SRV/docs/_build/markdown/api/services/arp_service.md @@ -0,0 +1,55 @@ +# ARP Service + +Сервис низкоуровневого ARP-сканирования локальной сети. + +Назначение: + +- Обнаружение активных узлов в пределах сетей хоста путём широковещательных ARP‑запросов от имени выбранного интерфейса. +- Помощь сервисам более высокого уровня (например, IPService) при проверке занятости адресов перед применением конфигураций. + +Особенности реализации: + +- Определяет подключённые сети интерфейса через netifaces и строит CIDR для сканирования. +- Формирует ARP‑пакеты с помощью scapy (Ether/ARP) и отправляет их с таймаутом. +- Добавляет локальный адрес интерфейса в результирующий список клиентов. + +Требования/ограничения: + +- Для отправки ARP‑кадров могут потребоваться повышенные привилегии или capability на сырой сокет. + +### *class* services.arp_service.NetworkScanner(interface=None, translations: Translations = Depends(translations_dependency)) + +Bases: `object` + +Инициализация сетевого сканера. + +Предоставляет методы для сканирования сети с использованием ARP-запросов и +вывода информации о клиентах. + +#### print_clients(clients) + +Выводит список адресов клиентов в формате таблицы. + +* **Parameters:** + **clients** (*List* *[**dict* *]*) – Список словарей с ключами “ip” и “mac”, + представляющих клиентов. + +Выводит IP-адреса и MAC-адреса в отсортированном по IP порядке. + +#### scan_network(attempts=3, timeout=2) + +Сканирует сеть для обнаружения активных клиентов. + +* **Parameters:** + * **attempts** (*int* *,* *optional*) – Количество попыток отправки ARP-запросов. + По умолчанию 3. + * **timeout** (*int* *,* *optional*) – Таймаут ожидания ответа в секундах. + По умолчанию 2. +* **Returns:** + Список словарей с ключами “ip” и “mac”, представляющих + : обнаруженных клиентов, включая локальные IP-адреса. +* **Return type:** + List[dict] + +#### NOTE +Учитывает локальные IP-адреса интерфейса и удаляет дубликаты. diff --git a/SRV/docs/_build/markdown/api/services/auth_service.md b/SRV/docs/_build/markdown/api/services/auth_service.md new file mode 100644 index 0000000..f9623fd --- /dev/null +++ b/SRV/docs/_build/markdown/api/services/auth_service.md @@ -0,0 +1,35 @@ +# Auth Service + +### *class* services.auth_service.AuthService(translations: Translations = Depends(translations_dependency)) + +Bases: `object` + +Сервис для регистрации, авторизации и управления сессиями + +#### create_access_token(data: dict) → str + +Создаёт токен + +#### get_current_user(token: str = Depends(OAuth2PasswordBearer)) → UserResponse + +Получает текущего пользователя по токену + +#### get_user_by_session(client_id: str) → dict + +Получает пользователя и токен по client_id + +#### login(user: UserLogin, client_id: str) → dict + +Авторизует пользователя, создаёт сессию и возвращает токен + +#### logout(client_id: str) + +Выполняет выход из системы, удаляя последнюю сессию для client_id + +#### register(user: UserCreate) → UserResponse + +Регистрирует нового пользователя + +#### verify_token(token: str) → dict | None + +Проверяет токен diff --git a/SRV/docs/_build/markdown/api/services/connect_service.md b/SRV/docs/_build/markdown/api/services/connect_service.md new file mode 100644 index 0000000..9c0c9fa --- /dev/null +++ b/SRV/docs/_build/markdown/api/services/connect_service.md @@ -0,0 +1,71 @@ +# Connect Service + +Сервис управления подключениями Wi‑Fi через nmcli. + +Назначение: + +- Предоставляет операции подключения/отключения к точкам доступа и проверки текущего статуса, ориентируясь на системный NetworkManager. + +Поведение: + +- Автоматически определяет активный Wi‑Fi‑интерфейс. +- Валидирует наличие SSID в листинге перед подключением и интерпретирует частые ошибки nmcli (неверный пароль, отсутствующая сеть и т.п.). + +Ограничения: + +- Требуются права для управления сетевыми соединениями в системе. +- В окружениях без NetworkManager команды nmcli будут недоступны. + +### *class* services.connect_service.WifiConnectionService(translations: Translations = Depends(translations_dependency)) + +Bases: `object` + +Сервис для управления подключением к Wi-Fi сетям с использованием nmcli. + +Предоставляет методы для подключения, отключения и проверки статуса Wi-Fi соединений. + +#### connect(ssid: str, password: str) → Tuple[bool, str | None] + +Подключается к Wi-Fi сети по SSID и паролю. + +* **Parameters:** + * **ssid** (*str*) – Идентификатор сети Wi-Fi. + * **password** (*str*) – Пароль для подключения. +* **Returns:** + Кортеж (успех, сообщение об ошибке). + : - Успех: (True, None). + - Ошибка: (False, сообщение об ошибке). +* **Return type:** + Tuple[bool, Optional[str]] +* **Raises:** + * **subprocess.CalledProcessError** – Если команда nmcli завершилась с ошибкой. + * **Exception** – Если произошла неизвестная ошибка при выполнении. + +#### disconnect(ssid: str) → Tuple[bool, str | None] + +Отключается от Wi-Fi сети по указанному SSID. + +* **Parameters:** + **ssid** (*str*) – Идентификатор сети Wi-Fi для отключения. +* **Returns:** + Кортеж (успех, сообщение об ошибке). + : - Успех: (True, None или сообщение, если подключение не найдено). + - Ошибка: (False, сообщение об ошибке). +* **Return type:** + Tuple[bool, Optional[str]] +* **Raises:** + * **subprocess.CalledProcessError** – Если команда nmcli завершилась с ошибкой. + * **Exception** – Если произошла неизвестная ошибка при выполнении. + +#### get_status() → Tuple[bool, str | None] + +Проверяет статус текущего подключения к Wi-Fi. + +* **Returns:** + Кортеж (успех, SSID или сообщение об ошибке). + : - Успех: (True, SSID текущей сети). + - Ошибка или отсутствие подключения: (False, сообщение об ошибке). +* **Return type:** + Tuple[bool, Optional[str]] +* **Raises:** + **Exception** – Если произошла ошибка при выполнении команды nmcli. diff --git a/SRV/docs/_build/markdown/api/services/firewalld_service.md b/SRV/docs/_build/markdown/api/services/firewalld_service.md new file mode 100644 index 0000000..bfd4951 --- /dev/null +++ b/SRV/docs/_build/markdown/api/services/firewalld_service.md @@ -0,0 +1,72 @@ +# Firewalld Service + +Сервис для управления firewalld через D‑Bus. + +Назначение: + +- Обёртка над интерфейсами org.fedoraproject.FirewallD1 для выполнения типовых операций по зонам: просмотр/изменение дефолтной зоны, добавление и удаление сервисов, портов, источников, перезагрузка конфигурации. + +Примечания: + +- Используется pydbus.SystemBus для доступа к системной шине. +- Методы генерируют дружелюбные исключения при ошибках, содержащие контекст операции. + +### *class* services.firewalld_service.FirewalldService + +Bases: `object` + +#### add_port(zone: str, port: int, protocol: str, timeout: int | None = 0) → None + +Add a port to a zone. + +#### add_service(zone: str, service: str, timeout: int | None = 0) → None + +Add a service to a zone. + +#### add_source(zone: str, source: str) → None + +Add a source to a zone. + +#### get_default_zone() → str + +Get the default zone. + +#### get_ports(zone: str) → List[str] + +Get list of ports in a zone. + +#### get_services(zone: str) → List[str] + +Get list of services in a zone. + +#### get_sources(zone: str) → List[str] + +Get list of sources in a zone. + +#### get_zone_settings(zone: str) → Dict + +Get all settings for a zone. + +#### get_zones() → List[str] + +Get list of all zones. + +#### reload() → None + +Reload firewall rules. + +#### remove_port(zone: str, port: int, protocol: str) → None + +Remove a port from a zone. + +#### remove_service(zone: str, service: str) → None + +Remove a service from a zone. + +#### remove_source(zone: str, source: str) → None + +Remove a source from a zone. + +#### set_default_zone(zone: str) → None + +Set the default zone. diff --git a/SRV/docs/_build/markdown/api/services/ip_service.md b/SRV/docs/_build/markdown/api/services/ip_service.md new file mode 100644 index 0000000..390ff87 --- /dev/null +++ b/SRV/docs/_build/markdown/api/services/ip_service.md @@ -0,0 +1,61 @@ +# IP Service + +Сервис проверки и применения IP‑настроек через NetworkManager (D‑Bus). + +Назначение: + +- Перед применением конфигурации проверяет занятость IP адреса, сканируя сегмент сети средствами ARP (через NetworkScanner). +- Применяет изменения профиля подключения через sdbus_async.networkmanager и выполняет переподключение интерфейса. + +Требования/ограничения: + +- Доступ к системной шине D‑Bus и права на изменения сетевых профилей. +- Структура входных данных должна соответствовать схеме ipv4_updates для корректного обновления вложенных полей у профиля. + +### *class* services.ip_service.IPService + +Bases: `object` + +Сервис проверки доступности IP-адреса и применения настроек сети. + +Предоставляет асинхронные методы для проверки занятости IP-адреса с использованием +ARP-сканирования и применения настроек через NetworkManager. + +#### *async* apply_ip_config(args: Dict[str, Any], translations: Translations = Depends(translations_dependency)) → None + +Применяет проверенные настройки IP к указанному соединению. + +Перезапускает шину D-Bus, обновляет настройки соединения через NetworkManager, +отключает и переподключает устройство к сети. + +* **Parameters:** + * **args** (*Dict* *[**str* *,* *Any* *]*) – Словарь с данными, включая: + - “connection_id” (str): Идентификатор соединения. + - “ipv4_updates” (Dict): Обновления настроек IPv4. + * **translations** (*Translations*) – Объект переводов. +* **Raises:** + * **ValueError** – Если соединение с указанным ID не найдено. + * **RuntimeError** – Если устройство для интерфейса не найдено. + +#### NOTE +Требуются права для изменения настроек через NetworkManager. + +#### *async* check_ip_config(args: Dict[str, Any], translations: Translations = Depends(translations_dependency)) → Dict[str, Any] + +Проверяет доступность IP-адреса перед его применением. + +Выполняет ARP-сканирование сети для проверки, занят ли указанный IP-адрес. +Перезапускает шину D-Bus перед выполнением. + +* **Parameters:** + * **args** (*Dict* *[**str* *,* *Any* *]*) – Словарь с данными, включая “ipv4_updates” + с полем “ipv4.address-data” для нового IP-адреса. + * **translations** (*Translations*) – Объект переводов. +* **Returns:** + Словарь с ключами: + : - ”available” (bool): Доступен ли IP-адрес. + - ”message” (str): Сообщение о результате проверки. +* **Return type:** + Dict[str, Any] +* **Raises:** + **Exception** – Если произошла ошибка при сканировании ARP. diff --git a/SRV/docs/_build/markdown/api/services/network_service.md b/SRV/docs/_build/markdown/api/services/network_service.md new file mode 100644 index 0000000..27780ef --- /dev/null +++ b/SRV/docs/_build/markdown/api/services/network_service.md @@ -0,0 +1,195 @@ +# Network Service + +Сервис чтения сетевого состояния через NetworkManager (D‑Bus). + +Назначение: + +- Предоставляет асинхронные методы для сборки унифицированных моделей сетевых интерфейсов (Ethernet/Wi‑Fi), их IP‑конфигураций, а также получения имени хоста. Используется API‑слоем для визуализации и управления. + +Особенности: + +- Фильтрация loopback и явно неактивных интерфейсов. +- Адаптация данных D‑Bus в pydantic‑модели (NetworkInterface, WiFiDevice, NetworkInterfacesContainer). + +### *class* services.network_service.NetworkService(translations: Translations = Depends(translations_dependency)) + +Bases: `object` + +Сервис для взаимодействия с NetworkManager через D-Bus. + +Предоставляет асинхронные методы для получения информации о сетевых интерфейсах, +их конфигурациях IP, Wi-Fi и состояниях. + +#### *async* get_activated_interfaces(initial_positions: Dict[str, Tuple[int, int]] = None) → List[NetworkInterface] + +Получает список активных сетевых интерфейсов. + +* **Parameters:** + **initial_positions** (*Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *,* *optional*) – Словарь начальных + координат (x, y) для интерфейсов. По умолчанию None. +* **Returns:** + Список активных интерфейсов (state == “100”). +* **Return type:** + List[NetworkInterface] + +#### *async* get_activated_interfaces_container(initial_positions: Dict[str, Tuple[int, int]] = None, container_x: int = 0, container_y: int = 0) → NetworkInterfacesContainer + +Получает объект, содержащий список активных интерфейсов и координаты контейнера. + +* **Parameters:** + * **initial_positions** (*Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *,* *optional*) – Словарь начальных + координат (x, y) для интерфейсов. По умолчанию None. + * **container_x** (*int* *,* *optional*) – Координата X контейнера. По умолчанию 0. + * **container_y** (*int* *,* *optional*) – Координата Y контейнера. По умолчанию 0. +* **Returns:** + Объект с активными интерфейсами и координатами. +* **Return type:** + NetworkInterfacesContainer + +#### *async* get_connection_name(device: sdbus_async.networkmanager.NetworkDeviceGeneric) → str + +Извлекает имя соединения (GENERAL.CONNECTION) для устройства. + +* **Parameters:** + **device** (*NetworkDeviceGeneric*) – Объект устройства NetworkManager. +* **Returns:** + Имя соединения или “unknown” в случае ошибки. +* **Return type:** + str +* **Raises:** + **Exception** – Если произошла ошибка при получении настроек соединения. + +#### *async* get_deactivated_interfaces(initial_positions: Dict[str, Tuple[int, int]] = None) → List[NetworkInterface] + +Получает список неактивных сетевых интерфейсов. + +* **Parameters:** + **initial_positions** (*Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *,* *optional*) – Словарь начальных + координат (x, y) для интерфейсов. По умолчанию None. +* **Returns:** + Список интерфейсов с state != “100”. +* **Return type:** + List[NetworkInterface] + +#### *async* get_deactivated_interfaces_container(initial_positions: Dict[str, Tuple[int, int]] = None, container_x: int = 0, container_y: int = 0) → NetworkInterfacesContainer + +Получает объект, содержащий список неактивных интерфейсов и координаты контейнера. + +* **Parameters:** + * **initial_positions** (*Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *,* *optional*) – Словарь начальных + координат (x, y) для интерфейсов. По умолчанию None. + * **container_x** (*int* *,* *optional*) – Координата X контейнера. По умолчанию 0. + * **container_y** (*int* *,* *optional*) – Координата Y контейнера. По умолчанию 0. +* **Returns:** + Объект с неактивными интерфейсами и координатами. +* **Return type:** + NetworkInterfacesContainer + +#### *async* get_hostname() → Dict[str, str] + +Возвращает имя хоста из команды hostname в формате JSON. + +* **Returns:** + Словарь с ключом “hostname” и значением имени хоста. +* **Return type:** + Dict[str, str] +* **Raises:** + **RuntimeError** – Если произошла ошибка при выполнении команды hostname + или обработке вывода. + +#### *async* get_interfaces_by_state(state: str, initial_positions: Dict[str, Tuple[int, int]] = None) → List[NetworkInterface] + +Получает список интерфейсов по указанному состоянию. + +* **Parameters:** + * **state** (*str*) – Состояние интерфейса (например, “100” для активных). + * **initial_positions** (*Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *,* *optional*) – Словарь начальных + координат (x, y) для интерфейсов. По умолчанию None. +* **Returns:** + Список интерфейсов с указанным состоянием. +* **Return type:** + List[NetworkInterface] + +#### *async* get_interfaces_container(state: str | None = None, initial_positions: Dict[str, Tuple[int, int]] = None, container_x: int = 0, container_y: int = 0) → NetworkInterfacesContainer + +Получает объект, содержащий список интерфейсов и координаты контейнера. + +* **Parameters:** + * **state** (*Optional* *[**str* *]* *,* *optional*) – Состояние интерфейсов (например, “100”). + По умолчанию None (все интерфейсы). + * **initial_positions** (*Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *,* *optional*) – Словарь начальных + координат (x, y) для интерфейсов. По умолчанию None. + * **container_x** (*int* *,* *optional*) – Координата X контейнера. По умолчанию 0. + * **container_y** (*int* *,* *optional*) – Координата Y контейнера. По умолчанию 0. +* **Returns:** + Объект с интерфейсами и координатами контейнера. +* **Return type:** + NetworkInterfacesContainer + +#### *async* get_ip_config(device: sdbus_async.networkmanager.NetworkDeviceGeneric, ip_version: str) → List[IndividualIPConfig] + +Получает конфигурацию IP для устройства. + +* **Parameters:** + * **device** (*NetworkDeviceGeneric*) – Объект устройства NetworkManager. + * **ip_version** (*str*) – Версия IP (“4” или “6”). +* **Returns:** + Список конфигураций IP, включая адреса и маршруты. +* **Return type:** + List[IndividualIPConfig] +* **Raises:** + **Exception** – Если произошла ошибка при получении данных IP. + +#### *async* get_ip_method(device: sdbus_async.networkmanager.NetworkDeviceGeneric, ip_type: str) → str + +Получает метод IP (например, “auto”, “manual”) для указанного устройства. + +* **Parameters:** + * **device** (*NetworkDeviceGeneric*) – Объект устройства NetworkManager. + * **ip_type** (*str*) – Тип IP (например, “ipv4” или “ipv6”). +* **Returns:** + Метод IP или “unknown” в случае ошибки. +* **Return type:** + str +* **Raises:** + **Exception** – Если произошла ошибка при получении настроек соединения. + +#### *async* get_network_interfaces(initial_positions: Dict[str, Tuple[int, int]] = None) → List[NetworkInterface | WiFiDevice] + +Получает список сетевых интерфейсов. + +* **Parameters:** + **initial_positions** (*Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *,* *optional*) – Словарь начальных + координат (x, y) для интерфейсов. По умолчанию None (используются (100, 100)). +* **Returns:** + Список объектов интерфейсов, + : включая Wi-Fi устройства. +* **Return type:** + List[Union[NetworkInterface, WiFiDevice]] + +Исключает интерфейсы типа LOOPBACK и неактивные состояния (state == “10”). + +#### *async* get_network_interfaces_container(initial_positions: Dict[str, Tuple[int, int]] | None = None) → NetworkInterfacesContainer + +Получает контейнер с сетевыми интерфейсами и координатами контейнера. + +* **Parameters:** + **initial_positions** (*Optional* *[**Dict* *[**str* *,* *Tuple* *[**int* *,* *int* *]* *]* *]* *,* *optional*) – Словарь начальных координат (x, y) для интерфейсов. По умолчанию None. +* **Returns:** + Объект с интерфейсами и координатами (0, 0). +* **Return type:** + NetworkInterfacesContainer + +#### *async* get_wifi_info(wifi_device: sdbus_async.networkmanager.NetworkDeviceWireless) → Dict[str, str | int | None] + +Получает информацию о Wi-Fi устройстве. + +* **Parameters:** + **wifi_device** (*NetworkDeviceWireless*) – Объект Wi-Fi устройства NetworkManager. +* **Returns:** + Словарь с данными Wi-Fi (SSID, BSSID, + : bitrate, strength, frequency, mode), где значения могут быть None. +* **Return type:** + Dict[str, Optional[Union[str, int]]] +* **Raises:** + **Exception** – Если произошла ошибка при получении данных точки доступа. diff --git a/SRV/docs/_build/markdown/api/services/settings_service.md b/SRV/docs/_build/markdown/api/services/settings_service.md new file mode 100644 index 0000000..bc73b07 --- /dev/null +++ b/SRV/docs/_build/markdown/api/services/settings_service.md @@ -0,0 +1,43 @@ +# Settings Service + +### *class* services.settings_service.SettingsService(translations: Translations = Depends(translations_dependency)) + +Bases: `object` + +Сервис для управления настройками и очистки данных сети. + +#### clear_all_data() → bool + +Очищает данные узлов всех подсетей и точек доступа Wi-Fi. + +* **Returns:** + True, если очистка успешна. +* **Return type:** + bool +* **Raises:** + **Exception** – Если произошла ошибка при записи в один из файлов. + +#### clear_subnet(subnet: str | None = None) → bool + +Очищает данные узлов подсети в указанном файле или во всех файлах. + +* **Parameters:** + **subnet** (*Optional* *[**str* *]*) – Подсеть в формате CIDR (например, “10.1.1.0/24”). + Если None, очищает все подсети. +* **Returns:** + True, если очистка успешна. +* **Return type:** + bool +* **Raises:** + **Exception** – Если произошла ошибка при записи в файл. + +#### clear_wifi() → bool + +Очищает данные точек доступа Wi-Fi в файле wifi.json. + +* **Returns:** + True, если очистка успешна. +* **Return type:** + bool +* **Raises:** + **Exception** – Если произошла ошибка при записи в файл. diff --git a/SRV/docs/_build/markdown/api/services/subnet_service.md b/SRV/docs/_build/markdown/api/services/subnet_service.md new file mode 100644 index 0000000..009e602 --- /dev/null +++ b/SRV/docs/_build/markdown/api/services/subnet_service.md @@ -0,0 +1,272 @@ +# Subnet Service + +### *class* services.subnet_service.DeviceInfoCollector(translations: Translations) + +Bases: `object` + +Класс для сбора информации об устройствах, включая вендоров и хостнеймы. + +Источники данных: +: - MacLookup: сопоставление префикса MAC (OUI) с названием производителя. + - DNS: gethostbyaddr с малым таймаутом для обратного разрешения имени. + - NetBIOS (nbtscan): опрос сегмента сети для извлечения NetBIOS‑имён. + +Политика кэширования: +: - Результаты get_vendor кэшируются с помощью functools.lru_cache. + - Результаты nbtscan аккумулируются в словарях nbtscan_cache/nbtscan_results + на время жизни экземпляра. + +#### get_hostname(ip: str) → str | None + +Получает хостнейм для указанного IP-адреса. + +Пробует сначала DNS, затем NetBIOS. + +* **Parameters:** + **ip** (*str*) – IP-адрес устройства. +* **Returns:** + Хостнейм или None, если не удалось определить. +* **Return type:** + Optional[str] + +#### get_vendor(mac: str) → str + +Получает вендора устройства по MAC-адресу. + +Использует кэширование для повышения производительности. + +* **Parameters:** + **mac** (*str*) – MAC-адрес устройства. +* **Returns:** + Название вендора или “Неизвестный” в случае ошибки. +* **Return type:** + str + +#### scan_nbtscan(subnet: str) → None + +Сканирует подсеть с помощью nbtscan для получения хостнеймов. + +Сохраняет результаты в кэш и логирует процесс. + +* **Parameters:** + **subnet** (*str*) – Подсеть в формате CIDR. + +### *class* services.subnet_service.DeviceStorage(base_path: str = 'storage/subnets', translations: Translations = None) + +Bases: `object` + +Класс для хранения и управления данными об устройствах. + +Формат файла подсети: + +```default +{ + "devices": [Device, ...] +} +``` + +Политика очистки: + +- Метод \_clean_old_devices удаляет оффлайн‑устройства, не наблюдавшиеся более 7 дней, + чтобы поддерживать актуальность списка. + +#### get_subnet_file(subnet: str) → Path + +Возвращает путь к файлу для конкретной подсети. + +Заменяет символы ‘/’ на ‘_’ для корректного имени файла. + +* **Parameters:** + **subnet** (*str*) – Подсеть в формате CIDR. +* **Returns:** + Путь к файлу. +* **Return type:** + Path + +#### load_devices(subnet: str) → Dict[str, Device] + +Загружает устройства для указанной подсети. + +Читает данные из JSON-файла и фильтрует устаревшие устройства. + +* **Parameters:** + **subnet** (*str*) – Подсеть в формате CIDR. +* **Returns:** + Словарь устройств с MAC как ключом. +* **Return type:** + Dict[str, Device] + +#### save_devices(subnet: str, devices: List[Device]) → None + +Сохраняет устройства для указанной подсети. + +Записывает данные в JSON-файл. + +* **Parameters:** + * **subnet** (*str*) – Подсеть в формате CIDR. + * **devices** (*List* *[**Device* *]*) – Список устройств для сохранения. +* **Raises:** + **Exception** – Если произошла ошибка при сохранении. + +### *class* services.subnet_service.NetworkScanner(interface: str, translations: Translations) + +Bases: `object` + +Класс для сканирования подсети с использованием ARP-запросов. + +Назначение: +: Обнаруживает активные устройства в локальной сети, отправляя широковещательные + ARP‑запросы по указанной подсети и собирая ответы (IP, MAC). + +Детали реализации: +: - Использует scapy (Ether + ARP) для генерации пакетов и srp для + отправки/получения на канальном уровне от имени заданного интерфейса. + - Таймаут ожидания ответа короткий (2 секунды), ориентирован на интерактивные + сценарии UI. + +Ограничения и замечания: +: - Требуются права для отправки низкоуровневых пакетов (capabilities/root). + - В сетях с фильтрацией широковещания количество обнаруженных устройств + может быть ограничено. + +#### scan(subnet: str) → List[Tuple[str, str]] + +Сканирует подсеть с использованием ARP-запросов. + +Отправляет ARP-пакеты для обнаружения активных устройств и возвращает +список кортежей (IP, MAC). + +* **Parameters:** + **subnet** (*str*) – Подсеть в формате CIDR (например, “10.1.1.0/24”). +* **Returns:** + Список кортежей (IP-адрес, MAC-адрес) обнаруженных устройств. +* **Return type:** + List[Tuple[str, str]] +* **Raises:** + **Exception** – Если произошла ошибка сканирования. + +### *class* services.subnet_service.PortScanner(interface: str, translations: Translations) + +Bases: `object` + +Класс для сканирования открытых портов на устройствах. + +Назначение: +: Плейсхолдер для будущего функционала активного сканирования TCP/UDP‑портов + у обнаруженных узлов. В текущей версии возвращает пустой список. + +План развития: +: - Добавить неблокирующее сканирование наиболее распространённых портов + (22, 80, 443 и т.д.) с ограничением по времени. + - Настраиваемые профили глубины и скорости сканирования. + +#### scan(ip: str) → List[str] + +Сканирует открытые порты на указанном IP-адресе. + +Пока возвращает пустой список, так как функциональность не реализована. + +* **Parameters:** + **ip** (*str*) – IP-адрес устройства для сканирования. +* **Returns:** + Список открытых портов (пока пустой). +* **Return type:** + List[str] + +### *class* services.subnet_service.SubnetService(translations: Translations) + +Bases: `object` + +Сервис для сканирования подсетей и управления устройствами. + +Роль сервиса: +: Объединяет сетевое сканирование (ARP), сбор дополнительной информации + (вендор, хостнейм), слияние с кэшем предыдущих результатов и персистентное + хранение данных по подсетям. Предоставляет вспомогательные операции для + локального узла и работы с заметками устройств. + +Поток выполнения скана (scan_subnet): +: 1. Определение подсети (вручную или авто по интерфейсу). + 2. Загрузка ранее сохранённых устройств подсети. + 3. Добавление локального устройства (если принадлежит подсети). + 4. ARP‑сканирование и параллельная обработка узлов (обогащение данных). + 5. Маркировка оффлайн‑узлов из кэша, не встреченных в текущем скане. + 6. Сортировка по IP и сохранение объединённого списка в JSON. + +#### add_note(mac: str, note: str, translations: Translations) → Tuple[bool, Tuple[str, Dict] | None] + +Добавляет заметку для устройства по MAC-адресу. + +Привязывает заметку к устройству, если оно существует. + +* **Parameters:** + * **mac** (*str*) – MAC-адрес устройства. + * **note** (*str*) – Текст заметки. + * **translations** (*Translations*) – Объект переводов для текущего языка. +* **Returns:** + Кортеж (успех, результат), + : где результат содержит код ошибки/успеха и данные. +* **Return type:** + Tuple[bool, Optional[Tuple[str, Dict]]] + +#### delete_note(mac: str, translations: Translations) → Tuple[bool, Tuple[str, Dict] | None] + +Удаляет заметку для устройства по MAC-адресу. + +Удаляет привязанную заметку, если она существует. + +* **Parameters:** + * **mac** (*str*) – MAC-адрес устройства. + * **translations** (*Translations*) – Объект переводов для текущего языка. +* **Returns:** + Кортеж (успех, результат), + : где результат содержит код ошибки/успеха и данные. +* **Return type:** + Tuple[bool, Optional[Tuple[str, Dict]]] + +#### scan_subnet(subnet: str | None = None) → SubnetScanResult + +Сканирует указанную подсеть и возвращает результаты. + +Выполняет ARP-сканирование, собирает информацию о устройствах и сохраняет данные. + +* **Parameters:** + **subnet** (*Optional* *[**str* *]*) – Подсеть в формате CIDR (например, “10.1.1.0/24”). + Если None или пустая строка, определяется автоматически. +* **Returns:** + Объект с результатами сканирования, содержащий список + : устройств или сообщение об ошибке. +* **Return type:** + SubnetScanResult +* **Raises:** + **Exception** – Если произошла ошибка сканирования. + +#### update_note(mac: str, note: str, translations: Translations) → Tuple[bool, Tuple[str, Dict] | None] + +Обновляет заметку для устройства по MAC-адресу. + +Изменяет существующую заметку, если она есть. + +* **Parameters:** + * **mac** (*str*) – MAC-адрес устройства. + * **note** (*str*) – Новый текст заметки. + * **translations** (*Translations*) – Объект переводов для текущего языка. +* **Returns:** + Кортеж (успех, результат), + : где результат содержит код ошибки/успеха и данные. +* **Return type:** + Tuple[bool, Optional[Tuple[str, Dict]]] + +### services.subnet_service.get_subnet_service(translations: Translations = Depends(translations_dependency)) + +Фабричная функция для создания экземпляра SubnetService. + +Использует зависимости FastAPI для получения объекта переводов и возвращает +экземпляр SubnetService с текущей локализацией. + +* **Parameters:** + **translations** (*Translations*) – Объект переводов для текущего языка. +* **Returns:** + Экземпляр сервиса для работы с подсетями. +* **Return type:** + SubnetService diff --git a/SRV/docs/_build/markdown/api/services/ufw_service.md b/SRV/docs/_build/markdown/api/services/ufw_service.md new file mode 100644 index 0000000..379e445 --- /dev/null +++ b/SRV/docs/_build/markdown/api/services/ufw_service.md @@ -0,0 +1,108 @@ +# UFW Service + +### *class* services.ufw_service.UFWService + +Bases: `object` + +Сервис взаимодействия с UFW (Uncomplicated Firewall). + +Назначение: +: - Чтение статуса и списка правил брандмауэра. + - Добавление, удаление и массовая обработка правил с поддержкой диапазонов портов, + комментариев и выбором протоколов. + +Детали реализации: +: - Команды выполняются через sudo ufw …; вывод парсится в модели pydantic. + - Для операций удаления соблюдается порядок с конца, чтобы не нарушать нумерацию. + +#### add_rules(rules: List[UFWRule]) → dict + +Добавляет правила UFW. + +* **Parameters:** + **rules** – Список правил для добавления +* **Returns:** + Результат добавления правил +* **Return type:** + dict + +#### add_rules_base(rules: List[UFWRule], direction: str = '') → bool + +Базовый метод для добавления правил UFW. + +* **Parameters:** + * **rules** – Список правил для добавления + * **direction** – Направление трафика (“in” или “out”) +* **Returns:** + True если все правила были успешно добавлены, False в противном случае +* **Return type:** + bool + +#### add_ufw_in_rules(rules: List[UFWRule]) → bool + +Добавляет входящие (in) правила UFW. + +* **Parameters:** + **rules** (*List* *[**UFWRule* *]*) – Список правил для добавления +* **Returns:** + True если все правила были успешно добавлены, False в противном случае +* **Return type:** + bool + +#### add_ufw_out_rules(rules: List[UFWRule]) → bool + +Добавляет исходящие (out) правила UFW. + +* **Parameters:** + **rules** (*List* *[**UFWRule* *]*) – Список правил для добавления +* **Returns:** + True если все правила были успешно добавлены, False в противном случае +* **Return type:** + bool + +#### delete_rules(rule_numbers: List[int]) → dict + +Удаляет правила UFW по их номерам. + +* **Parameters:** + **rule_numbers** (*List* *[**int* *]*) – Список номеров правил для удаления +* **Returns:** + Результат операции удаления +* **Return type:** + dict + +#### disable_ufw() → bool + +Выключает UFW. + +* **Returns:** + True если успешно выключен, False в противном случае +* **Return type:** + bool + +#### enable_ufw() → bool + +Включает UFW. + +* **Returns:** + True если успешно включен, False в противном случае +* **Return type:** + bool + +#### get_ufw_rules() → UFWRulesResponse + +Получает список правил UFW. + +* **Returns:** + Объект, содержащий статус UFW и список правил +* **Return type:** + UFWRulesResponse + +#### get_ufw_status() → UFWStatus + +Проверяет статус UFW. + +* **Returns:** + Объект с информацией о статусе UFW +* **Return type:** + UFWStatus diff --git a/SRV/docs/_build/markdown/api/services/wifi_service.md b/SRV/docs/_build/markdown/api/services/wifi_service.md new file mode 100644 index 0000000..2bfee67 --- /dev/null +++ b/SRV/docs/_build/markdown/api/services/wifi_service.md @@ -0,0 +1,61 @@ +# Wifi Service + +### *class* services.wifi_service.WifiService(translations: Translations = Depends(translations_dependency)) + +Bases: `object` + +Сервис для сканирования текущих Wi‑Fi точек доступа и заметок. + +Источники данных: +: - pywifi для базового сканирования и получения списка AP. + - iw dev scan для уточнения частоты, сигнала и безопасности. + - MacLookup для определения вендора по BSSID. + +Политики: +: - Выбор лучшего AP по SSID по уровню сигнала. + - Кэширование определения вендора. + - Сохранение SSID даже без заметок для будущих операций. + +#### add_note(ssid: str, note: str) → Tuple[bool, str | None] + +Добавляет заметку к сети Wi-Fi по SSID. + +#### delete_note(ssid: str) → Tuple[bool, str | None] + +Удаляет заметку сети Wi-Fi по SSID. + +#### get_vendor(mac: str) → str + +Определяет вендора по MAC-адресу с использованием кэширования. + +#### scan_wifi(timeout: int = 30) → WifiScanResult + +Сканирует текущие Wi-Fi точки доступа. + +#### update_note(ssid: str, note: str) → Tuple[bool, str | None] + +Обновляет заметку сети Wi-Fi по SSID. + +### *class* services.wifi_service.WifiStorage(storage_path: str = 'storage/wifi/wifi.json', translations: Translations = Depends(translations_dependency)) + +Bases: `object` + +Класс для хранения данных о Wi‑Fi сетях и их заметках по SSID. + +Формат: +: { + : “networks”: [{“ssid”: str, “note”: Optional[str]}] +
+ } + +Поведение: +: - Создаёт директорию хранения при инициализации, ведёт логирование путей. + - Валидация структуры при чтении, безопасная запись с Unicode и отступами. + +#### load_notes() → Dict[str, str | None] + +Загружает заметки по SSID из файла хранения. + +#### save_notes(notes: Dict[str, str | None]) → None + +Сохраняет заметки по SSID в файл. diff --git a/SRV/docs/_build/markdown/api/storage.md b/SRV/docs/_build/markdown/api/storage.md new file mode 100644 index 0000000..f0850e3 --- /dev/null +++ b/SRV/docs/_build/markdown/api/storage.md @@ -0,0 +1,4 @@ +# Хранилища + +* [storage.json_storage](storage/json_storage.md) +* [storage.session_storage](storage/session_storage.md) diff --git a/SRV/docs/_build/markdown/api/storage/json_storage.md b/SRV/docs/_build/markdown/api/storage/json_storage.md new file mode 100644 index 0000000..261e32d --- /dev/null +++ b/SRV/docs/_build/markdown/api/storage/json_storage.md @@ -0,0 +1,75 @@ +# storage.json_storage + +### *class* storage.json_storage.JsonStorage(file_path: str = '/etc/gonets/users.json') + +Bases: `object` + +Хранилище пользователей в JSON-файле. + +Назначение: +: Обеспечивает простое файловое хранилище для учетных записей пользователей + без полноценной СУБД. Подходит для встраиваемых окружений и сценариев, + где важна минимальная зависимость от внешних сервисов. + +Формат данных: +: JSON‑структура вида: + { +
+ > “users”: [ + > : {“id”: int, “username”: str, “password_hash”: str, “is_admin”: bool}, + > … +
+ > ], + > “next_id”: int +
+ } + +Безопасность: +: Пароли никогда не сохраняются в открытом виде. Для хеширования используется + passlib.context.CryptContext со схемой bcrypt. Файл создаётся с правами + доступа 0o600 (только владелец). + +Ограничения и замечания: +: - Отсутствует конкурентный доступ/блокировки файла — при использовании в + многопроцессной среде может потребоваться внешняя синхронизация. + - Имя файла и каталог по умолчанию /etc/gonets/users.json предполагают + наличие прав на запись и предварительную подготовку окружения. + +#### create_user(user: UserCreate) → UserResponse + +Создаёт нового пользователя с хешированием пароля. + +* **Parameters:** + **user** (*UserCreate*) – Объект с данными нового пользователя (username, password, is_admin). +* **Returns:** + Объект с данными созданного пользователя (id, username, is_admin). +* **Return type:** + UserResponse +* **Raises:** + * **ValueError** – Если пользователь с таким именем уже существует. + * **Exception** – Если произошла ошибка при записи данных. + +#### get_user_by_username(username: str) → dict | None + +Получает данные пользователя по имени. + +* **Parameters:** + **username** (*str*) – Имя пользователя для поиска. +* **Returns:** + Словарь с данными пользователя или None, если пользователь не найден. +* **Return type:** + Optional[dict] +* **Raises:** + **Exception** – Если произошла ошибка при чтении файла. + +#### verify_password(plain_password: str, hashed_password: str) → bool + +Проверяет соответствие введённого пароля хэшированному. + +* **Parameters:** + * **plain_password** (*str*) – Введённый пользователем пароль. + * **hashed_password** (*str*) – Хэшированный пароль из хранилища. +* **Returns:** + True, если пароль верен, False в противном случае. +* **Return type:** + bool diff --git a/SRV/docs/_build/markdown/api/storage/session_storage.md b/SRV/docs/_build/markdown/api/storage/session_storage.md new file mode 100644 index 0000000..87a7991 --- /dev/null +++ b/SRV/docs/_build/markdown/api/storage/session_storage.md @@ -0,0 +1,95 @@ +# storage.session_storage + +### *class* storage.session_storage.SessionStorage(file_path: str = '/etc/gonets/sessions.json') + +Bases: `object` + +Хранилище сессий пользователей в JSON-файле. + +Назначение: +: Лёгкое файловое хранилище для сессионных токенов, сопоставленных с + client_id (например, IP клиента). Предназначено для сред без БД и + persistent‑кэшей. Обеспечивает базовые операции и авто‑очистку протухших + сессий. + +Формат данных: +: { + : “sessions”: { + : “”: { + : “username”: str, + “token”: str, + “client_id”: str, + “created_at”: ISO8601 str, + “expiry”: ISO8601 str +
+ } +
+ } + +Политика TTL: +: Каждая сессия действует 30 минут. При создании/чтении/удалении вызывается + clean_expired_sessions() для удаления протухших записей. + +Ограничения: +: - Нет файловых блокировок: в многопроцессных конфигурациях возможны гонки. + - Размещение по умолчанию /etc/gonets/sessions.json требует прав на запись. + +#### clean_expired_sessions() + +Удаляет все истекшие сессии из хранилища. + +* **Raises:** + **Exception** – Если произошла ошибка при чтении или записи данных. + +#### NOTE +Проверяет срок действия каждой сессии и удаляет те, что истекли, +записывая обновлённые данные. + +#### create_session(username: str, token: str, client_id: str) → str + +Создаёт новую сессию и возвращает уникальный session_id. + +* **Parameters:** + * **username** (*str*) – Имя пользователя, для которого создаётся сессия. + * **token** (*str*) – Токен аутентификации. + * **client_id** (*str*) – Идентификатор клиента. +* **Returns:** + Уникальный идентификатор сессии (session_id). +* **Return type:** + str +* **Raises:** + **Exception** – Если произошла ошибка при создании или записи сессии. + +#### NOTE +Удаляет истекшие сессии перед созданием новой и устанавливает срок +действия 30 минут. + +#### delete_session(session_id: str) + +Удаляет сессию по указанному session_id. + +* **Parameters:** + **session_id** (*str*) – Уникальный идентификатор сессии. +* **Raises:** + **Exception** – Если произошла ошибка при чтении или записи данных. + +#### NOTE +Очищает истекшие сессии перед удалением. + +#### get_latest_session(client_id: str) → Dict | None + +Получает последнюю активную сессию для указанного client_id. + +* **Parameters:** + **client_id** (*str*) – Идентификатор клиента. +* **Returns:** + Словарь с данными последней активной сессии, включая + : ”session_id”, или None, если сессия не найдена. +* **Return type:** + Optional[Dict] +* **Raises:** + **Exception** – Если произошла ошибка при чтении или обработке данных. + +#### NOTE +Очищает истекшие сессии перед поиском и возвращает сессию с самым +поздним временем создания. diff --git a/SRV/docs/_build/markdown/api/utils.md b/SRV/docs/_build/markdown/api/utils.md new file mode 100644 index 0000000..764079f --- /dev/null +++ b/SRV/docs/_build/markdown/api/utils.md @@ -0,0 +1,3 @@ +# Утилиты + +* [utils.i18n](utils/i18n.md) diff --git a/SRV/docs/_build/markdown/api/utils/i18n.md b/SRV/docs/_build/markdown/api/utils/i18n.md new file mode 100644 index 0000000..7ccd96f --- /dev/null +++ b/SRV/docs/_build/markdown/api/utils/i18n.md @@ -0,0 +1,23 @@ +# utils.i18n + +Утилиты локализации и зависимости переводов для FastAPI. + +Содержимое модуля: +: - get_translations(): фабрика зависимости FastAPI, считывающая локаль из + query‑параметра locale, cookie locale или заголовка Accept-Language + (по приоритету), с дефолтом ru. Возвращает функцию‑зависимость, которая + подгружает babel.support.Translations из каталога SRV/locales. + - \_(): удобная обёртка для получения перевода строки с использованием + текущей локали (или дефолтного ru, если контекст запроса не передан). + +Особенности: +: - При отсутствии словаря перевода для выбранной локали выполняется fallback на + русскую локаль, что гарантирует наличие строк интерфейса. + - Локаль определяется только по первому языку из Accept-Language (без + региональных суффиксов) для упрощения. + - Модуль ведёт отладочное логирование выбора и загрузки локали. + +### utils.i18n.get_translations() → callable + +Создаёт зависимость для загрузки переводов на основе заголовка Accept-Language +или параметра запроса ‘locale’. По умолчанию используется русский язык. diff --git a/SRV/docs/_build/markdown/index.md b/SRV/docs/_build/markdown/index.md new file mode 100644 index 0000000..83c609c --- /dev/null +++ b/SRV/docs/_build/markdown/index.md @@ -0,0 +1,45 @@ +# GONETS SRV Documentation + +Добро пожаловать в документацию серверной части GONETS (SRV). + +## Содержание + +## Разделы + +* [Сервисы](api/services.md) + * [ARP Service](api/services/arp_service.md) + * [Auth Service](api/services/auth_service.md) + * [Connect Service](api/services/connect_service.md) + * [Firewalld Service](api/services/firewalld_service.md) + * [IP Service](api/services/ip_service.md) + * [Network Service](api/services/network_service.md) + * [Settings Service](api/services/settings_service.md) + * [Subnet Service](api/services/subnet_service.md) + * [UFW Service](api/services/ufw_service.md) + * [Wifi Service](api/services/wifi_service.md) +* [Модели](api/models.md) + * [models.auth](api/models/auth.md) + * [models.network](api/models/network.md) + * [models.request](api/models/request.md) + * [models.subnet](api/models/subnet.md) + * [models.ufw](api/models/ufw.md) + * [models.wifi](api/models/wifi.md) +* [API эндпоинты](api/endpoints.md) + * [api.v1.auth](api/endpoints/auth.md) + * [api.v1.ip](api/endpoints/ip.md) + * [api.v1.network](api/endpoints/network.md) + * [api.v1.settings](api/endpoints/settings.md) + * [api.v1.subnet](api/endpoints/subnet.md) + * [api.v1.ufw](api/endpoints/ufw.md) + * [api.v1.websocket](api/endpoints/websocket.md) +* [Конфигурация](api/config.md) + * [config.cors](api/config/cors.md) + * [config.init_config](api/config/init_config.md) + * [config.ports](api/config/ports.md) +* [Core](api/core.md) + * [core.cli_executor](api/core/cli_executor.md) +* [Хранилища](api/storage.md) + * [storage.json_storage](api/storage/json_storage.md) + * [storage.session_storage](api/storage/session_storage.md) +* [Утилиты](api/utils.md) + * [utils.i18n](api/utils/i18n.md) diff --git a/SRV/docs/conf.py b/SRV/docs/conf.py index 56db4c0..f480eee 100644 --- a/SRV/docs/conf.py +++ b/SRV/docs/conf.py @@ -23,6 +23,8 @@ napoleon_google_docstring = False napoleon_numpy_docstring = False napoleon_use_param = True napoleon_use_rtype = True +napoleon_google_docstring = True +napoleon_numpy_docstring = False html_theme = 'furo' @@ -45,6 +47,16 @@ autodoc_mock_imports = [ 'pywifi', 'sdbus', 'sdbus_async', 'sdbus_async.networkmanager', 'dbus', 'dbus.mainloop', 'dbus.mainloop.glib', 'pydbus', 'mac_vendor_lookup', + # mock problematic local modules when docs are built + 'config.init_config', +] + +# Also prevent autosummary from importing mocked modules +autosummary_mock_imports = autodoc_mock_imports + +# Suppress noisy warnings for mocked objects +suppress_warnings = [ + 'autodoc.mocked_object', ] # Environment flag so code can short-circuit heavy side effects during import @@ -55,4 +67,5 @@ autodoc_default_options = { 'undoc-members': True, 'private-members': False, 'show-inheritance': True, + 'no-index': True, } diff --git a/SRV/poetry.lock b/SRV/poetry.lock index 0c5df61..c2b8ebf 100644 --- a/SRV/poetry.lock +++ b/SRV/poetry.lock @@ -1495,13 +1495,13 @@ files = [ [[package]] name = "markdown-it-py" -version = "4.0.0" +version = "3.0.0" description = "Python port of markdown-it. Markdown parsing, done right!" optional = false -python-versions = ">=3.10" +python-versions = ">=3.8" files = [ - {file = "markdown_it_py-4.0.0-py3-none-any.whl", hash = "sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147"}, - {file = "markdown_it_py-4.0.0.tar.gz", hash = "sha256:cb0a2b4aa34f932c007117b194e945bd74e0ec24133ceb5bac59009cda1cb9f3"}, + {file = "markdown-it-py-3.0.0.tar.gz", hash = "sha256:e3f60a94fa066dc52ec76661e37c851cb232d92f9886b15cb560aaada2df8feb"}, + {file = "markdown_it_py-3.0.0-py3-none-any.whl", hash = "sha256:355216845c60bd96232cd8d8c40e8f9765cc86f46880e43a8fd22dc1a1a8cab1"}, ] [package.dependencies] @@ -1509,12 +1509,13 @@ mdurl = ">=0.1,<1.0" [package.extras] benchmarking = ["psutil", "pytest", "pytest-benchmark"] -compare = ["commonmark (>=0.9,<1.0)", "markdown (>=3.4,<4.0)", "markdown-it-pyrs", "mistletoe (>=1.0,<2.0)", "mistune (>=3.0,<4.0)", "panflute (>=2.3,<3.0)"] +code-style = ["pre-commit (>=3.0,<4.0)"] +compare = ["commonmark (>=0.9,<1.0)", "markdown (>=3.4,<4.0)", "mistletoe (>=1.0,<2.0)", "mistune (>=2.0,<3.0)", "panflute (>=2.3,<3.0)"] linkify = ["linkify-it-py (>=1,<3)"] -plugins = ["mdit-py-plugins (>=0.5.0)"] +plugins = ["mdit-py-plugins"] profiling = ["gprof2dot"] -rtd = ["ipykernel", "jupyter_sphinx", "mdit-py-plugins (>=0.5.0)", "myst-parser", "pyyaml", "sphinx", "sphinx-book-theme (>=1.0,<2.0)", "sphinx-copybutton", "sphinx-design"] -testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions", "requests"] +rtd = ["jupyter_sphinx", "mdit-py-plugins", "myst-parser", "pyyaml", "sphinx", "sphinx-copybutton", "sphinx-design", "sphinx_book_theme"] +testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions"] [[package]] name = "markupsafe" @@ -1614,6 +1615,25 @@ files = [ {file = "markupsafe-3.0.3.tar.gz", hash = "sha256:722695808f4b6457b320fdc131280796bdceb04ab50fe1795cd540799ebe1698"}, ] +[[package]] +name = "mdit-py-plugins" +version = "0.5.0" +description = "Collection of plugins for markdown-it-py" +optional = false +python-versions = ">=3.10" +files = [ + {file = "mdit_py_plugins-0.5.0-py3-none-any.whl", hash = "sha256:07a08422fc1936a5d26d146759e9155ea466e842f5ab2f7d2266dd084c8dab1f"}, + {file = "mdit_py_plugins-0.5.0.tar.gz", hash = "sha256:f4918cb50119f50446560513a8e311d574ff6aaed72606ddae6d35716fe809c6"}, +] + +[package.dependencies] +markdown-it-py = ">=2.0.0,<5.0.0" + +[package.extras] +code-style = ["pre-commit"] +rtd = ["myst-parser", "sphinx-book-theme"] +testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions"] + [[package]] name = "mdurl" version = "0.1.2" @@ -1862,6 +1882,32 @@ files = [ {file = "multidict-6.7.0.tar.gz", hash = "sha256:c6e99d9a65ca282e578dfea819cfa9c0a62b2499d8677392e09feaf305e9e6f5"}, ] +[[package]] +name = "myst-parser" +version = "4.0.1" +description = "An extended [CommonMark](https://spec.commonmark.org/) compliant parser," +optional = false +python-versions = ">=3.10" +files = [ + {file = "myst_parser-4.0.1-py3-none-any.whl", hash = "sha256:9134e88959ec3b5780aedf8a99680ea242869d012e8821db3126d427edc9c95d"}, + {file = "myst_parser-4.0.1.tar.gz", hash = "sha256:5cfea715e4f3574138aecbf7d54132296bfd72bb614d31168f48c477a830a7c4"}, +] + +[package.dependencies] +docutils = ">=0.19,<0.22" +jinja2 = "*" +markdown-it-py = ">=3.0,<4.0" +mdit-py-plugins = ">=0.4.1,<1.0" +pyyaml = "*" +sphinx = ">=7,<9" + +[package.extras] +code-style = ["pre-commit (>=4.0,<5.0)"] +linkify = ["linkify-it-py (>=2.0,<3.0)"] +rtd = ["ipython", "sphinx (>=7)", "sphinx-autodoc2 (>=0.5.0,<0.6.0)", "sphinx-book-theme (>=1.1,<2.0)", "sphinx-copybutton", "sphinx-design", "sphinx-pyscript", "sphinx-tippy (>=0.4.3)", "sphinx-togglebutton", "sphinxext-opengraph (>=0.9.0,<0.10.0)", "sphinxext-rediraffe (>=0.2.7,<0.3.0)"] +testing = ["beautifulsoup4", "coverage[toml]", "defusedxml", "pygments (<2.19)", "pytest (>=8,<9)", "pytest-cov", "pytest-param-files (>=0.6.0,<0.7.0)", "pytest-regressions", "sphinx-pytest"] +testing-docutils = ["pygments", "pytest (>=8,<9)", "pytest-param-files (>=0.6.0,<0.7.0)"] + [[package]] name = "netaddr" version = "1.3.0" @@ -3228,6 +3274,25 @@ sphinx = ">=4.0" [package.extras] docs = ["furo", "ipython", "myst-parser", "sphinx-copybutton", "sphinx-inline-tabs"] +[[package]] +name = "sphinx-markdown-builder" +version = "0.6.8" +description = "A Sphinx extension to add markdown generation support." +optional = false +python-versions = ">=3.7" +files = [ + {file = "sphinx_markdown_builder-0.6.8-py3-none-any.whl", hash = "sha256:f04ab42d52449363228b9104569c56b778534f9c41a168af8cfc721a1e0e3edc"}, + {file = "sphinx_markdown_builder-0.6.8.tar.gz", hash = "sha256:6141b566bf18dd1cd515a0a90efd91c6c4d10fc638554fab2fd19cba66543dd7"}, +] + +[package.dependencies] +docutils = "*" +sphinx = ">=5.1.0" +tabulate = "*" + +[package.extras] +dev = ["black", "bumpver", "coveralls", "flake8", "isort", "pip-tools", "pylint", "pytest", "pytest-cov", "sphinx (>=5.3.0)", "sphinxcontrib-plantuml", "sphinxcontrib.httpdomain"] + [[package]] name = "sphinxcontrib-applehelp" version = "2.0.0" @@ -3367,6 +3432,20 @@ files = [ [package.dependencies] paramiko = ">=1.8.0" +[[package]] +name = "tabulate" +version = "0.9.0" +description = "Pretty-print tabular data" +optional = false +python-versions = ">=3.7" +files = [ + {file = "tabulate-0.9.0-py3-none-any.whl", hash = "sha256:024ca478df22e9340661486f85298cff5f6dcdba14f3813e8830015b9ed1948f"}, + {file = "tabulate-0.9.0.tar.gz", hash = "sha256:0095b12bf5966de529c0feb1fa08671671b3368eec77d7ef7ab114be2c068b3c"}, +] + +[package.extras] +widechars = ["wcwidth"] + [[package]] name = "tomlkit" version = "0.13.3" @@ -4092,4 +4171,4 @@ cffi = ["cffi (>=1.17,<2.0)", "cffi (>=2.0.0b)"] [metadata] lock-version = "2.0" python-versions = "^3.11" -content-hash = "c6c0a22996d81f671212b16c7df393c6f9be8c7fb189c15b6a2b9b63259e9242" +content-hash = "ae26c1e051193ae0ceaf8f6fb0914b9fdcadb360295a36394af6a71108d117be" diff --git a/SRV/pyproject.toml b/SRV/pyproject.toml index 24da327..98d28df 100644 --- a/SRV/pyproject.toml +++ b/SRV/pyproject.toml @@ -42,6 +42,8 @@ poetry-plugin-export = "^1.9.0" babel = "^2.17.0" polib = "^1.2.0" docutils = "^0.21.2" +myst-parser = "^4.0.1" +sphinx-markdown-builder = "^0.6.8" [tool.poetry.group.dev.dependencies] @@ -49,6 +51,8 @@ sphinx = "^8.2.3" furo = "^2025.9.25" sphinx-autodoc-typehints = "2.5.0" sphinxcontrib-napoleon = "^0.7" +myst-parser = "^4.0.1" +sphinx-markdown-builder = "^0.6.8" [build-system] requires = ["poetry-core"] diff --git a/SRV/services/firewalld_service.py b/SRV/services/firewalld_service.py index 2605f05..1593f4d 100644 --- a/SRV/services/firewalld_service.py +++ b/SRV/services/firewalld_service.py @@ -2,14 +2,13 @@ Сервис для управления firewalld через D‑Bus. Назначение: -- Обёртка над интерфейсами `org.fedoraproject.FirewallD1` для выполнения - типовых операций по зонам: просмотр/изменение дефолтной зоны, добавление и - удаление сервисов, портов, источников, перезагрузка конфигурации. + +- Обёртка над интерфейсами `org.fedoraproject.FirewallD1` для выполнения типовых операций по зонам: просмотр/изменение дефолтной зоны, добавление и удаление сервисов, портов, источников, перезагрузка конфигурации. Примечания: + - Используется `pydbus.SystemBus` для доступа к системной шине. -- Методы генерируют дружелюбные исключения при ошибках, содержащие контекст - операции. +- Методы генерируют дружелюбные исключения при ошибках, содержащие контекст операции. """ from re import DEBUG from typing import Dict, List, Optional diff --git a/SRV/services/ip_service.py b/SRV/services/ip_service.py index c974727..8cf6354 100644 --- a/SRV/services/ip_service.py +++ b/SRV/services/ip_service.py @@ -2,15 +2,14 @@ Сервис проверки и применения IP‑настроек через NetworkManager (D‑Bus). Назначение: -- Перед применением конфигурации проверяет занятость IP адреса, сканируя сегмент - сети средствами ARP (через `NetworkScanner`). -- Применяет изменения профиля подключения через `sdbus_async.networkmanager` и - выполняет переподключение интерфейса. + +- Перед применением конфигурации проверяет занятость IP адреса, сканируя сегмент сети средствами ARP (через `NetworkScanner`). +- Применяет изменения профиля подключения через `sdbus_async.networkmanager` и выполняет переподключение интерфейса. Требования/ограничения: + - Доступ к системной шине D‑Bus и права на изменения сетевых профилей. -- Структура входных данных должна соответствовать схеме `ipv4_updates` для - корректного обновления вложенных полей у профиля. +- Структура входных данных должна соответствовать схеме `ipv4_updates` для корректного обновления вложенных полей у профиля. """ from typing import Dict, Any from sdbus_async.networkmanager import ( diff --git a/SRV/services/network_service.py b/SRV/services/network_service.py index c960c94..1fa691d 100644 --- a/SRV/services/network_service.py +++ b/SRV/services/network_service.py @@ -2,14 +2,13 @@ Сервис чтения сетевого состояния через NetworkManager (D‑Bus). Назначение: -- Предоставляет асинхронные методы для сборки унифицированных моделей - сетевых интерфейсов (Ethernet/Wi‑Fi), их IP‑конфигураций, а также получения - имени хоста. Используется API‑слоем для визуализации и управления. + +- Предоставляет асинхронные методы для сборки унифицированных моделей сетевых интерфейсов (Ethernet/Wi‑Fi), их IP‑конфигураций, а также получения имени хоста. Используется API‑слоем для визуализации и управления. Особенности: + - Фильтрация loopback и явно неактивных интерфейсов. -- Адаптация данных D‑Bus в pydantic‑модели (`NetworkInterface`, `WiFiDevice`, - `NetworkInterfacesContainer`). +- Адаптация данных D‑Bus в pydantic‑модели (`NetworkInterface`, `WiFiDevice`, `NetworkInterfacesContainer`). """ from typing import List, Dict, Tuple, Union, Optional from sdbus_async.networkmanager import ( diff --git a/SRV/services/subnet_service.py b/SRV/services/subnet_service.py index ca6e0f7..af65ed6 100644 --- a/SRV/services/subnet_service.py +++ b/SRV/services/subnet_service.py @@ -245,15 +245,16 @@ class DeviceInfoCollector: class DeviceStorage: """Класс для хранения и управления данными об устройствах. - Формат файла подсети: - JSON‑структура вида + Формат файла подсети:: + { "devices": [Device, ...] } Политика очистки: - - Метод `_clean_old_devices` удаляет оффлайн‑устройства, не наблюдавшиеся - более 7 дней, чтобы поддерживать актуальность списка. + + - Метод `_clean_old_devices` удаляет оффлайн‑устройства, не наблюдавшиеся более 7 дней, + чтобы поддерживать актуальность списка. """ def __init__(self, base_path: str = "storage/subnets", translations: Translations = None): """Инициализирует хранилище устройств.