quoter/docs/how-it-works.md

🚀 Как работает Quoter

Quoter - это высокопроизводительный файловый сервис с автоматическим ресайзингом изображений, системой квот и многоуровневой защитой.

📋 Архитектура системы

1. 🔐 Аутентификация и безопасность

• JWT валидация: Проверка токенов с валидацией формата, длины и подписи
• Rate limiting: Ограничение запросов по IP с Redis-хранением
• Request validation: Проверка размера, заголовков и подозрительных паттернов
• Session management: Получение данных пользователя из Redis сессий

2. 📤 Процесс загрузки файлов

Клиент → [Auth] → [Quota Check] → [Upload] → [Thumbnail Generation] → [S3 Storage]

Этапы обработки:

1. Валидация токена: JWT проверка + извлечение user_id
2. Проверка квот: Текущая квота пользователя (лимит 12 ГБ)
3. Стриминг загрузка: Чтение файла по частям с проверкой лимитов
4. MIME детекция: Автоматическое определение типа файла
5. Генерация UUID: Уникальное имя файла
6. Загрузка в Storj: Основное хранилище
7. Асинхронная генерация миниатюр: Для изображений

3. 🖼️ Система миниатюр

Предопределенные размеры:

• 10px - микро-превью
• 40px - аватары
• 110px - маленькие превью
• 300px - средние изображения
• 600px - стандартные изображения
• 800px - большие изображения
• 1400px - максимальный размер

Lazy Generation:

• Миниатюры создаются по первому запросу
• Оригинал возвращается пока генерируется миниатюра
• Асинхронная обработка в фоне
• Кэширование в S3

4. 📂 Система файлов (Multi-Cloud)

┌─ Storj S3 (primary) ─┐    ┌─ AWS S3 (fallback) ─┐
│ • Новые файлы        │    │ • Legacy файлы       │
│ • Миниатюры          │    │ • Backup             │
│ • Основное хранилище │    │ • Migration source   │
└─────────────────────┘    └──────────────────────┘

Логика обслуживания:

1. Проверка в Storj (основное хранилище)
2. Fallback на AWS S3 (legacy файлы)
3. Автоматическая миграция AWS → Storj при запросе
4. Поддержка различных путей (production/image/, etc.)

5. 🔍 Обслуживание файлов (GET)

Request → [Security] → [Cache Check] → [File Lookup] → [Resize] → [Response]

Процесс:

1. Security проверки: Rate limits, подозрительные пути
2. ETag кэширование: HTTP 304 для неизмененных файлов
3. Path parsing: Извлечение имени файла и размера
4. File lookup: Поиск в базе путей или по паттерну
5. Resize logic: Выбор ближайшего размера или генерация
6. Cached response: Оптимизированные заголовки

6. 💾 Управление квотами

Redis структуры:

quota:user:{user_id}           # Текущая квота (bytes)
files:user:{user_id}           # Список файлов пользователя
file_info:{filename}           # MIME-type и метаданные
rate_limit:{type}:{ip}         # Счетчики rate limiting

Проверки:

• Превентивная проверка перед загрузкой
• Streaming проверка по частям
• Atomic обновление после успешной загрузки
• Лимит: 12 ГБ на пользователя

7. 🛡️ Система безопасности

Уровни защиты:

1. Network: Security headers, CORS, payload limits
2. Application: Rate limiting, request validation
3. Authentication: JWT validation, session management
4. Monitoring: Логирование атак, метрики

Rate Limits:

• Общие запросы: 100/мин (блокировка 5 мин)
• Загрузка файлов: 10/5мин (блокировка 10 мин)
• Аутентификация: 20/15мин (блокировка 30 мин)

🔄 Поток данных

Загрузка файла

sequenceDiagram
    Client->>+Quoter: POST / (multipart)
    Quoter->>+Redis: Validate session
    Redis-->>-Quoter: User data
    Quoter->>+Redis: Check quota
    Redis-->>-Quoter: Current usage
    Quoter->>+Storj: Upload file
    Storj-->>-Quoter: Success
    Quoter->>+Background: Generate thumbnails
    Quoter->>+Redis: Update quota
    Quoter-->>-Client: File URL

Получение файла

sequenceDiagram
    Client->>+Quoter: GET /file_300.jpg
    Quoter->>+Cache: Check ETag
    Cache-->>-Quoter: 304 or miss
    Quoter->>+Storj: Get thumbnail
    alt Thumbnail exists
        Storj-->>Quoter: File data
    else Thumbnail missing
        Storj-->>Quoter: Original file
        Quoter->>Background: Generate thumbnail
    end
    Quoter-->>-Client: Image + headers

📊 Производительность

Оптимизации

• HTTP кэширование: ETag, immutable cache headers
• Lazy thumbnail generation: Генерация по требованию
• Асинхронная обработка: Неблокирующие операции
• Local + Redis cache: Многоуровневое кэширование
• Streaming uploads: Обработка больших файлов по частям

Мониторинг

• Время обработки запросов
• Статистика генерации миниатюр
• Метрики rate limiting
• Использование квот по пользователям
• Ошибки и security события