uploader-bot/docs/SANIC_TO_FASTAPI_MIGRATION_PLAN.md

План миграции с Sanic на FastAPI для uploader-bot

Обзор текущей архитектуры

Статус миграции

ЧАСТИЧНО МИГРИРОВАН - В проекте уже используются оба фреймворка одновременно:

• ✅ Основное приложение FastAPI уже создано в main.py
• ✅ Частично реализованы FastAPI роуты в fastapi_v3_routes.py и fastapi_node_routes.py
• ⚠️ Основная функциональность все еще на Sanic

Гибридная архитектура

Приложение запускается в одном из режимов (определяется в main.py:19-44):

1. FastAPI режим - если доступен FastAPI или установлена переменная USE_FASTAPI=true
2. Sanic режим - fallback к Sanic приложению
3. Минимальный режим - если ни один фреймворк недоступен

Инвентаризация Sanic эндпоинтов

1. Аутентификация и авторизация (auth_routes.py)

Blueprint: auth_bp = Blueprint("auth", url_prefix="/api/v1/auth")

Метод	Путь	Функция	Описание
POST	/register	register_user()	Регистрация пользователя с валидацией
POST	/login	login_user()	Вход с JWT токенами
POST	/refresh	refresh_tokens()	Обновление access токенов
POST	/logout	logout_user()	Выход с инвалидацией сессии
GET	/me	get_current_user()	Информация о текущем пользователе
PUT	/me	update_current_user()	Обновление профиля
POST	/api-keys	create_api_key()	Создание API ключей
GET	/sessions	get_user_sessions()	Список активных сессий
DELETE	/sessions/<session_id>	revoke_session()	Отзыв сессии

Особенности:

• Rate limiting декораторы
• Комплексная валидация с Pydantic схемами
• JWT токены с ротацией
• Поддержка API ключей
• Управление сессиями

2. Управление контентом (content_routes.py)

Blueprint: content_bp = Blueprint("content", url_prefix="/api/v1/content")

Метод	Путь	Функция	Описание
POST	/	create_content()	Создание контента с метаданными
GET	/<content_id>	get_content()	Получение контента с кешированием
PUT	/<content_id>	update_content()	Обновление метаданных
POST	/search	search_content()	Поиск с фильтрами и пагинацией
GET	/<content_id>/download	download_content()	Скачивание с контролем доступа

Особенности:

• Комплексная система разрешений
• Redis кеширование
• Streaming downloads
• Квоты пользователей
• Статистика доступа

3. Файловое хранилище (storage_routes.py)

Blueprint: storage_bp = Blueprint("storage", url_prefix="/api/v1/storage")

Метод	Путь	Функция	Описание
POST	/upload	initiate_upload()	Инициация chunked upload
POST	/upload/<upload_id>/chunk	upload_chunk()	Загрузка chunk'а файла
GET	/upload/<upload_id>/status	get_upload_status()	Статус загрузки
DELETE	/upload/<upload_id>	cancel_upload()	Отмена загрузки
DELETE	/files/<content_id>	delete_file()	Удаление файла
GET	/quota	get_storage_quota()	Информация о квоте
GET	/stats	get_storage_stats()	Статистика хранилища
POST	/cleanup	cleanup_orphaned_files()	Очистка (админ)

Особенности:

• Chunked uploads с прогрессом
• Валидация файлов и типов
• Управление квотами
• Background cleanup

4. Блокчейн интеграция (blockchain_routes.py)

Blueprint: blockchain_bp = Blueprint("blockchain", url_prefix="/api/v1/blockchain")

Метод	Путь	Функция	Описание
GET	/wallet/balance	get_wallet_balance()	Баланс TON кошелька
GET	/wallet/transactions	get_wallet_transactions()	История транзакций
POST	/transaction/send	send_transaction()	Отправка TON транзакций
GET	/transaction/<tx_hash>/status	get_transaction_status()	Статус транзакции
POST	/wallet/create	create_wallet()	Создание кошелька
GET	/stats	get_blockchain_stats()	Статистика блокчейна

Особенности:

• TON блокчейн интеграция
• Безопасное хранение приватных ключей
• Лимиты транзакций
• Monitoring и статистика

5. Системное здоровье (health_routes.py)

Blueprint: health_bp = Blueprint("health", version=1)

Метод	Путь	Функция	Описание
GET	/health	health_check()	Базовая проверка
GET	/health/detailed	detailed_health_check()	Детальная проверка компонентов
GET	/health/ready	readiness_check()	Kubernetes readiness
GET	/health/live	liveness_check()	Kubernetes liveness
GET	/metrics	prometheus_metrics()	Prometheus метрики
GET	/stats	system_stats()	Системная статистика
GET	/debug/info	debug_info()	Debug информация

6. MY Network API (my_network_sanic.py)

Blueprint: bp = Blueprint("my_network", url_prefix="/api/my")

Метод	Путь	Функция	Описание
GET	/node/info	get_node_info()	Информация о ноде
GET	/node/peers	get_node_peers()	Список пиров
POST	/node/peers/connect	connect_to_peer()	Подключение к пиру
DELETE	/node/peers/<peer_id>	disconnect_peer()	Отключение пира
GET	/content/list	get_content_list()	Список контента в сети
GET	/content/<content_hash>/exists	check_content_exists()	Проверка существования
GET	/sync/status	get_sync_status()	Статус синхронизации
POST	/sync/start	start_network_sync()	Запуск синхронизации
GET	/network/stats	get_network_stats()	Статистика сети
GET	/health	health_check()	Здоровье сети

7. Мониторинг MY Network (my_monitoring_sanic.py)

Blueprint: bp = Blueprint("my_monitoring", url_prefix="/api/my/monitor")

Метод	Путь	Функция	Описание
GET	/	monitoring_dashboard()	HTML дашборд
GET	/ascii	get_ascii_status()	ASCII статус
GET	/live	live_monitoring_data()	Живые данные

8. Межузловое общение (node_communication.py)

Blueprint: node_bp = Blueprint("node", url_prefix="/api/node")

Метод	Путь	Функция	Описание
POST	/handshake	node_handshake()	Хэндшейк между нодами
POST	/content/sync	content_sync()	Синхронизация контента
POST	/network/ping	network_ping()	Пинг между нодами
GET	/network/status	network_status()	Статус ноды
POST	/network/discover	network_discover()	Обнаружение нод

9. Простые роуты

• account.py - одна функция s_api_v1_account_get()
• _system.py - системные функции с git info и статусами

Анализ существующих FastAPI роутов

1. V3 API совместимость (fastapi_v3_routes.py)

Уже реализовано:

• /api/v3/node/status - статус ноды
• /api/v3/network/stats - статистика сети
• /api/v3/content/list - список контента
• /api/v1/node - совместимость с v1
• /api/my/monitor - мониторинг MY Network
• /api/my/handshake - хэндшейк MY Network

2. Межузловое общение (fastapi_node_routes.py)

Уже реализовано:

• /api/node/handshake - обработка хэндшейка
• /api/node/content/sync - синхронизация контента
• /api/node/network/ping - пинг между нодами
• /api/node/network/status - статус ноды (GET)
• /api/node/network/discover - обнаружение нод

⚠️ ДУБЛИРОВАНИЕ: Межузловое общение реализовано И в Sanic, И в FastAPI!

Анализ Middleware

Текущий Sanic Middleware (middleware.py)

Критически важные компоненты:

1. SecurityMiddleware - CORS, CSP, безопасные заголовки
2. RateLimitMiddleware - лимитирование запросов через Redis
3. AuthenticationMiddleware - JWT токены, API ключи, права
4. CryptographicMiddleware - ed25519 подписи для межузлового общения
5. RequestContextMiddleware - контекст запроса, логирование

Middleware Pipeline:

1. maintenance_middleware() - режим обслуживания
2. request_middleware() - основной пайплайн
3. response_middleware() - обработка ответов
4. exception_middleware() - обработка ошибок

Особенности:

• Ed25519 криптографические подписи для межузлового общения
• Rate limiting с различными паттернами
• Комплексная аутентификация
• Детальное логирование и метрики

Совместимость с FastAPI

✅ Совместимые компоненты:

• Логирование и контекст
• Базовая безопасность
• CORS

⚠️ Требуют адаптации:

• Rate limiting (Sanic-специфичный код)
• Аутентификация (декораторы и middleware)
• Ed25519 криптография (заголовки и проверка подписей)
• Обработка исключений (Sanic exceptions)

Зависимости и совместимость

Анализ requirements.txt

fastapi==0.104.1          # ✅ Уже включен
uvicorn==0.24.0           # ✅ ASGI сервер
sanic==23.12.1            # ⚠️ Нужно удалить после миграции
sqlalchemy==2.0.23        # ✅ Совместим
redis==5.0.1              # ✅ Совместим
PyNaCl==1.5.0            # ✅ Ed25519 криптография
pyjwt==2.8.0             # ✅ JWT токены
bcrypt==4.1.2            # ✅ Хеширование паролей

Конфликтов зависимостей НЕТ - обе библиотеки могут сосуществовать.

Детальный план миграции

Фаза 1: Подготовка (1-2 дня)

1.1 Создание FastAPI Middleware

# app/api/fastapi_middleware.py
from fastapi import FastAPI, Request, Response
from fastapi.middleware.base import BaseHTTPMiddleware

class FastAPISecurityMiddleware(BaseHTTPMiddleware):
    # Адаптация SecurityMiddleware
    
class FastAPIRateLimitMiddleware(BaseHTTPMiddleware):
    # Адаптация RateLimitMiddleware
    
class FastAPIAuthMiddleware(BaseHTTPMiddleware):
    # Адаптация AuthenticationMiddleware
    
class FastAPICryptoMiddleware(BaseHTTPMiddleware):
    # Адаптация CryptographicMiddleware

1.2 Создание FastAPI Dependencies

# app/api/fastapi_dependencies.py
from fastapi import Depends, HTTPException, Request
from typing import Optional

async def get_current_user(request: Request) -> Optional[User]:
    # Извлечение пользователя из токена
    
async def require_auth(user: User = Depends(get_current_user)) -> User:
    # Требование авторизации
    
async def check_permissions(permission: str):
    # Проверка разрешений
    
async def check_rate_limit(pattern: str = "api"):
    # Проверка rate limit

1.3 Создание Pydantic моделей

# app/api/fastapi_models.py
from pydantic import BaseModel
from typing import List, Optional
from datetime import datetime

class UserResponse(BaseModel):
    id: str
    username: str
    email: str
    # ... остальные поля

class ContentResponse(BaseModel):
    id: str
    title: str
    # ... остальные поля

Фаза 2: Миграция маршрутов по модулям (7-10 дней)

2.1 Приоритет 1: Аутентификация (2 дня)

# app/api/fastapi_auth_routes.py
from fastapi import APIRouter, Depends, HTTPException
from fastapi.security import HTTPBearer

router = APIRouter(prefix="/api/v1/auth", tags=["auth"])

@router.post("/register")
async def register_user(user_data: UserRegistrationSchema):
    # Миграция register_user()
    
@router.post("/login") 
async def login_user(credentials: UserLoginSchema):
    # Миграция login_user()

Ключевые изменения:

• Sanic response.json() → FastAPI return dict
• Sanic request.json → FastAPI Pydantic models
• Sanic декораторы → FastAPI Depends()
• Sanic Blueprint → FastAPI APIRouter

2.2 Приоритет 2: Контент и хранилище (3 дня)

# app/api/fastapi_content_routes.py
# app/api/fastapi_storage_routes.py

Сложности:

• Streaming responses для downloads
• File uploads с validation
• Chunked uploads

2.3 Приоритет 3: Блокчейн интеграция (2 дня)

# app/api/fastapi_blockchain_routes.py

2.4 Приоритет 4: MY Network и мониторинг (3 дня)

# app/api/fastapi_my_network_routes.py
# app/api/fastapi_monitoring_routes.py

Сложности:

• HTML templates для monitoring dashboard
• WebSocket connections (если есть)

Фаза 3: Удаление дублирования (1-2 дня)

3.1 Объединение межузлового общения

• Удалить node_communication.py (Sanic версия)
• Оставить fastapi_node_routes.py
• Проверить совместимость ed25519 подписей

3.2 Консолидация роутинга

• Удалить регистрацию Sanic blueprints из __init__.py
• Добавить все FastAPI роутеры в main FastAPI app

Фаза 4: Обновление инициализации (1 день)

4.1 Модификация main.py

# Удалить create_sanic_app() и run_sanic_server()
# Сделать FastAPI режимом по умолчанию
def get_app_mode():
    return 'fastapi'  # Принудительно FastAPI

4.2 Обновление lifecycle управления

# Перенести EnhancedSanic функциональность в FastAPI
@app.on_event("startup")
async def startup_event():
    # Инициализация БД, Redis, ed25519, MY Network
    
@app.on_event("shutdown") 
async def shutdown_event():
    # Graceful shutdown

Фаза 5: Тестирование и оптимизация (2-3 дня)

5.1 Тестирование

• Unit тесты для всех endpoints
• Integration тесты для межузлового общения
• Load testing для performance
• Тестирование ed25519 криптографии

5.2 Очистка кодовой базы

• Удалить Sanic imports
• Удалить sanic из requirements.txt
• Обновить docker configurations
• Обновить documentation

Потенциальные проблемы и решения

1. Ed25519 криптографические подписи

Проблема: Sanic-специфичная обработка заголовков и контекста Решение:

• Создать FastAPI middleware для ed25519
• Использовать FastAPI dependency injection
• Сохранить полную совместимость протокола

2. Rate Limiting

Проблема: Sanic-специфичные декораторы и middleware Решение:

• Портировать на FastAPI middleware + dependencies
• Сохранить Redis backend
• Использовать slowapi библиотеку как альтернативу

3. File Uploads и Streaming

Проблема: Разные API для file handling Решение:

• FastAPI UploadFile для uploads
• StreamingResponse для downloads
• Сохранить chunked upload логику

4. WebSocket connections (если есть)

Проблема: Потенциальные WebSocket endpoints Решение:

• FastAPI имеет нативную поддержку WebSocket
• Портировать с минимальными изменениями

5. HTML Templates

Проблема: Jinja2 templates в monitoring Решение:

• FastAPI совместим с Jinja2
• Использовать FastAPI templating patterns

Mermaid диаграммы архитектуры

Текущая гибридная архитектура

graph TB
    Client[Client Requests] --> Main[main.py]
    Main --> Mode{App Mode}
    
    Mode -->|FastAPI| FastAPI[FastAPI App]
    Mode -->|Sanic| Sanic[Sanic App] 
    Mode -->|Minimal| Minimal[Minimal Server]
    
    FastAPI --> FV3[fastapi_v3_routes.py]
    FastAPI --> FNode[fastapi_node_routes.py]
    
    Sanic --> SAuth[auth_routes.py]
    Sanic --> SContent[content_routes.py] 
    Sanic --> SStorage[storage_routes.py]
    Sanic --> SBlockchain[blockchain_routes.py]
    Sanic --> SHealth[health_routes.py]
    Sanic --> SMyNet[my_network_sanic.py]
    Sanic --> SMonitor[my_monitoring_sanic.py]
    Sanic --> SNode[node_communication.py]
    
    subgraph "Shared Components"
        DB[(Database)]
        Redis[(Redis Cache)]
        Ed25519[Ed25519 Crypto]
        MyNetwork[MY Network Service]
    end
    
    FastAPI --> DB
    FastAPI --> Redis
    FastAPI --> Ed25519
    FastAPI --> MyNetwork
    
    Sanic --> DB
    Sanic --> Redis  
    Sanic --> Ed25519
    Sanic --> MyNetwork

Целевая FastAPI архитектура

graph TB
    Client[Client Requests] --> FastAPI[FastAPI App]
    
    FastAPI --> Auth[auth_routes.py]
    FastAPI --> Content[content_routes.py]
    FastAPI --> Storage[storage_routes.py] 
    FastAPI --> Blockchain[blockchain_routes.py]
    FastAPI --> Health[health_routes.py]
    FastAPI --> MyNet[my_network_routes.py]
    FastAPI --> Monitor[monitoring_routes.py]
    FastAPI --> Node[node_routes.py]
    FastAPI --> V3Compat[v3_compat_routes.py]
    
    subgraph "FastAPI Middleware Stack"
        Security[Security Middleware]
        RateLimit[Rate Limit Middleware]
        AuthMW[Auth Middleware]
        Crypto[Crypto Middleware]
        Context[Context Middleware]
    end
    
    FastAPI --> Security
    Security --> RateLimit
    RateLimit --> AuthMW
    AuthMW --> Crypto
    Crypto --> Context
    
    subgraph "Shared Services"
        DB[(Database)]
        Redis[(Redis Cache)]
        Ed25519[Ed25519 Crypto]
        MyNetwork[MY Network Service]
    end
    
    Context --> DB
    Context --> Redis
    Context --> Ed25519
    Context --> MyNetwork

Оценка трудозатрат

Фаза	Компонент	Время	Сложность
1	Middleware адаптация	2 дня	Высокая
2.1	Auth routes	2 дня	Средняя
2.2	Content + Storage	3 дня	Высокая
2.3	Blockchain	2 дня	Средняя
2.4	MY Network + Monitoring	3 дня	Высокая
3	Удаление дублирования	1 день	Низкая
4	Обновление инициализации	1 день	Средняя
5	Тестирование	3 дня	Высокая
Итого		17 дней

Рекомендации

1. Поэтапная миграция

• НЕ делать big bang migration
• Мигрировать по одному модулю
• Поддерживать работоспособность на каждом этапе

2. Сохранение совместимости

• Сохранить все API endpoints и форматы
• Особое внимание к ed25519 межузловому протоколу
• Сохранить все headers и форматы ответов

3. Тщательное тестирование

• Unit tests для каждого migrated endpoint
• Integration tests для межузлового общения
• Performance testing
• Backwards compatibility testing

4. Мониторинг миграции

• Логирование всех изменений
• Метрики производительности
• Error tracking
• Rollback plan для каждой фазы

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

• Обновить API документацию
• Автоматическая генерация OpenAPI docs
• Обновить deployment guides

Заключение

Проект уже находится в переходном состоянии с частичной поддержкой FastAPI. Основная сложность миграции заключается в:

1. Сложном middleware stack с ed25519 криптографией
2. Большом количестве endpoints (40+ эндпоинтов)
3. Межузловом протоколе который требует точной совместимости
4. File upload/download функциональности

Однако, благодаря:

• ✅ Уже частично созданной FastAPI инфраструктуре
• ✅ Отсутствию конфликтов зависимостей
• ✅ Хорошо структурированному коду
• ✅ Использованию SQLAlchemy (framework-agnostic)

Миграция выполнима в течение 2-3 недель при правильном планировании и поэтапном подходе.

Ключевой фактор успеха: Сохранение полной совместимости ed25519 межузлового протокола для корректной работы распределенной MY Network.