quoter/docs/architecture.md

Архитектура

Обзор системы

Quoter - это микросервис для управления файлами с поддержкой квот, миниатюр и интеграции с S3 хранилищами.

Компоненты системы

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web Client    │    │   Mobile App    │    │   API Client    │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │      Quoter Service       │
                    │    (Actix Web Server)     │
                    └─────────────┬─────────────┘
                                  │
          ┌───────────────────────┼───────────────────────┐
          │                       │                       │
    ┌─────▼─────┐         ┌───────▼──────┐         ┌─────▼─────┐
    │   Redis   │         │  Core API    │         │   S3/Storj│
    │ (Quotas & │         │(Auth & Shout)│         │ (Storage) │
    │  Cache)   │         │              │         │           │
    └───────────┘         └──────────────┘         └───────────┘

Основные модули

1. AppState (src/app_state.rs)

Центральное состояние приложения, содержащее:

• Подключения к Redis, Storj S3, AWS S3
• Методы для работы с квотами
• Кэширование списка файлов

2. Handlers (src/handlers/)

Обработчики HTTP запросов:

• upload.rs - загрузка файлов
• proxy.rs - получение файлов и генерация миниатюр
• quota.rs - управление квотами
• serve_file.rs - обслуживание файлов

3. Auth (src/auth.rs)

Аутентификация через GraphQL API ядра:

• Валидация JWT токенов
• Управление файлами пользователей в Redis

4. Core (src/core.rs)

Интеграция с API ядра:

• Получение данных shout для оверлеев

5. Thumbnail (src/thumbnail.rs)

Обработка изображений:

• Создание миниатюр различных размеров
• Поддержка различных форматов

6. S3 Utils (src/s3_utils.rs)

Утилиты для работы с S3:

• Загрузка/скачивание файлов
• Определение MIME типов
• Генерация ключей

Поток данных

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

sequenceDiagram
    participant Client
    participant Quoter
    participant Core API
    participant Redis
    participant S3

    Client->>Quoter: POST / (file + token)
    Quoter->>Core API: Validate token
    Core API-->>Quoter: User ID
    Quoter->>Redis: Check quota
    Redis-->>Quoter: Current quota
    Quoter->>S3: Upload file
    S3-->>Quoter: Success
    Quoter->>Redis: Update quota
    Quoter->>Redis: Save file info
    Quoter-->>Client: Filename

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

sequenceDiagram
    participant Client
    participant Quoter
    participant Redis
    participant S3

    Client->>Quoter: GET /filename
    Quoter->>Redis: Get file path
    Redis-->>Quoter: File path
    Quoter->>S3: Check file exists
    S3-->>Quoter: File exists
    Quoter->>S3: Download file
    S3-->>Quoter: File data
    Quoter-->>Client: File content

Структура данных

Redis схемы

Квоты пользователей

Key: quota:{user_id}
Type: String
Value: bytes_used (u64)
TTL: None (permanent)

Файлы пользователей

Key: {user_id}
Type: Set
Value: [filename1, filename2, ...]
TTL: None (permanent)

Маппинг путей файлов

Key: filepath_mapping
Type: Hash
Field: filename
Value: filepath
TTL: None (permanent)

Информация о файлах

Key: files:{filename}
Type: String
Value: mime_type
TTL: None (permanent)

S3 структура

bucket/
├── original_files/
│   ├── image1.jpg
│   ├── image2.png
│   └── document.pdf
├── thumbnails/
│   ├── image1_10.jpg
│   ├── image1_40.jpg
│   ├── image1_110.jpg
│   ├── image1_300.jpg
│   ├── image1_600.jpg
│   ├── image1_800.jpg
│   └── image1_1400.jpg
└── webp_thumbnails/
    ├── image1_10.jpg/webp
    ├── image1_40.jpg/webp
    └── ...

Безопасность

Аутентификация

• JWT токены через GraphQL API ядра
• Валидация токенов для всех операций записи

Авторизация

• Проверка квот перед загрузкой
• Изоляция файлов по пользователям

CORS

• Настроен для кросс-доменных запросов
• Поддержка credentials

Масштабирование

Горизонтальное масштабирование

• Stateless архитектура
• Redis как общее хранилище состояния
• S3 как общее файловое хранилище

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

• Асинхронная обработка запросов
• Кэширование списка файлов
• Ленивая генерация миниатюр

Мониторинг

• Структурированное логирование
• Метрики использования квот
• Отслеживание ошибок