Generate Sphinx docs in markdown

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‑структура вида:
+  {
+  <br/>
+  > “users”: [
+  > : {“id”: int, “username”: str, “password_hash”: str, “is_admin”: bool},
+  >   …
+  <br/>
+  > ],
+  > “next_id”: int
+  <br/>
+  }
+
+Безопасность:
+: Пароли никогда не сохраняются в открытом виде. Для хеширования используется
+  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

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”: {
+    : “<session_id>”: {
+      : “username”: str,
+        “token”: str,
+        “client_id”: str,
+        “created_at”: ISO8601 str,
+        “expiry”: ISO8601 str
+    <br/>
+    }
+  <br/>
+  }
+
+Политика 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
+Очищает истекшие сессии перед поиском и возвращает сессию с самым
+поздним временем создания.