Проект “Облачное хранилище файлов” #

Многопользовательское файловое облако. Пользователи сервиса могут использовать его для загрузки и хранения файлов. Источником вдохновения для проекта является Google Drive.

Что нужно знать #

Python - коллекции, ООП
pip/Poetry
Backend
- Django, DRF
- Upload файлов, заголовки HTTP запросов, cookies, cессии
Базы данных
- PostreSQL
- DjangoORM
- Миграции
- Представление о NoSQL хранилищах
Frontend - HTML/CSS, Bootstrap
Docker - контейнеры, образы, volumes, Docker Compose
Тесты - интеграционное тестирование, TestCase, LiveServerTestCase
Деплой - облачный хостинг, командная строка Linux, Docker

Мотивация проекта #

Использование возможностей Django
Практика с Docker и Docker Compose
Первый проект, где студент самостоятельно разрабатывает структуру БД
Знакомство с NoSQL хранилищем S3 для хранения файлов, Redis для хранения сессий
Реализация многопользовательского приложения

Функционал приложения #

Работа с пользователями:

Регистрация
Авторизация
Logout

Работа с файлами и папками:

Загрузка (upload) файлов и папок
Создание новой пустой папки (аналогично созданию новой папки в проводнике)
Удаление
Переименование
Скачивание файлов и папок

REST API #

Архитектурный стиль - RPC для авторизации и регистрации, REST для всего остального.
Все эндпоинты существуют под общим путём /api. Пути ниже относительны его, пример - /api/auth/sign-up.
Механизм авторизации - сессии.
Формат запросов и ответов - JSON, кроме скачивания и аплоада файлов.

Ответ в случае ошибки #

Актуально для всех методов.

Тело ответа:

{
  "message": "Текст ошибки"
}

Тело ответа может содержать другие поля (которые по-умолчанию отправляет Spring).

Регистрация и авторизация #

Регистрация #

POST /auth/sign-up

Тело запроса (application/json):

{
  "username": "user_1",
  "password": "password"
}

Ответ в случае успеха: 201 Created со следующим телом:

{
  "username": "user_1"
}

При регистрации юзеру сразу создаётся сессия и выставляется кука.

Коды ошибок:

400 - ошибки валидации (пример - слишком короткий username)
409 - username занят
500 - неизвестная ошибка

Авторизация #

POST /auth/sign-in

Тело запроса (application/json):

{
  "username": "user_1",
  "password": "password"
}

Тело ответа в случае успеха (200 OK):

{
  "username": "user_1"
}

Коды ошибок:

400 - ошибки валидации (пример - слишком короткий username)
401 - неверные данные (такого пользователя нет, или пароль неправильный)
500 - неизвестная ошибка

Выход из аккаунта (логаут) #

POST /auth/sign-out

Тела запроса нет.

Тело ответа в случае успеха (204 No Content) пустое.

Коды ошибок:

401 - запрос исполняется неавторизованным юзером
500 - неизвестная ошибка

Пользователи #

Текущий пользователь #

GET /user/me

Ответ в случае успеха: 200 OK со следующим телом:

{
  "username": "user_1"
}

Коды ошибок:

401 - пользователь не авторизован
500 - неизвестная ошибка

Работа с файлами и папками #

Терминология:

Ресурс - файл или папка
Путь к ресурсу - полный путь состоит из иерархии папок, плюс имени ресурса
- Пример для файла - folder1/folder2/file.txt
- Пример для папки - folder1/folder2/

Ресурсы #

Получение информации о ресурсе

GET /resource?path=$path

Для всех запросов ниже, параметр path - полный путь к ресурсу в url-encoded формате. Путь к папке должен заканчиваться на /. Это необходимо, чтобы отличить папку и файл с одинаковым названием, которые могут сосуществовать вместе в одной корневой директории.

Ответ в случае успеха: 200 OK со следующим телом (appication/json):

{
  "path": "folder1/folder2/", // путь к папке, в которой лежит ресурс
  "name": "file.txt",
  "size": 123, // размер файла в байтах. Если ресурс - папка, это поле отсутствует
  "type": "FILE" // DIRECTORY или FILE
}

Коды ошибок:

400 - невалидный или отсутствующий путь
401 - пользователь не авторизован
404 - ресурс не найден
500 - неизвестная ошибка

Удаление ресурса

DELETE /resource?path=$path

Ответ в случае успеха: 204 No Content без тела:

Коды ошибок:

400 - невалидный или отсутствующий путь
401 - пользователь не авторизован
404 - ресурс не найден
500 - неизвестная ошибка

Скачивание ресурса

GET /resource/download?path=$path

Ответ в случае успеха - 200 OK и бинарное содержимое файла с Content-Type: application/octet-stream.

Папка скачивается в формате zip архива её содержимого.

Коды ошибок:

400 - невалидный или отсутствующий путь
401 - пользователь не авторизован
404 - ресурс не найден
500 - неизвестная ошибка

Переименование/перемещение ресурса

POST /resource/move?from=$from&to=$to

GET параметры - старый и новый полные пути к ресурсу в URL-encoded формате.

При переименовании меняется только имя файла
При перемещении меняется только путь к файлу

Ответ в случае успеха - 200 OK. Тело (application/json):

{
  "path": "folder1/folder2/", // путь к папке, в которой лежит перемещённый ресурс
  "name": "file.txt", // имя перемещённого ресурса
  "size": 123, // размер файла в байтах. Если ресурс - папка, это поле отсутствует
  "type": "FILE" // DIRECTORY или FILE
}

Коды ошибок:

400 - невалидный или отсутствующий путь
401 - пользователь не авторизован
404 - ресурс не найден
409 - ресурс, лежащий по пути to уже существует
500 - неизвестная ошибка

Поиск

GET /resource/search?query=$query

GET параметр query - поисковый запрос в URL-encoded формате.

Ответ в случае успеха: 200 OK со следующим телом (appication/json). Коллекция найденных ресурсов:

[
  {
    "path": "folder1/folder2/", // путь к папке, в которой лежит ресурс
    "name": "file.txt",
    "size": 123, // размер файла в байтах. Если ресурс - папка, это поле отсутствует
    "type": "FILE" // DIRECTORY или FILE
  }
]

Коды ошибок:

400 - невалидный или отсутствующий поисковый запрос
401 - пользователь не авторизован
500 - неизвестная ошибка

Аплоад

POST resource?path=$path

GET параметр path - путь к папке, в которую мы загружаем ресурс(ы).

Тело запроса содержит данные из file input в формате MultipartFile. Если в имени файла будет указана поддиректория (например, upload_folder/test.txt) - то при загрузке в storage_folder/ будет создана такая директория. В итоге файл после загрузки будет находиться в storage_folder/upload_folder/test.txt. Это позволяет загружать файлы, папки и рекурсивно вложенные подпапки одним запросом.

Ответ в случае успеха: 201 Created со следующим телом (appication/json). Коллекция загруженных ресурсов:

[
  {
    "path": "folder1/folder2/", // путь к папке, в которой лежит ресурс
    "name": "file.txt",
    "size": 123, // размер файла в байтах. Если ресурс - папка, это поле отсутствует
    "type": "FILE" // DIRECTORY или FILE
  }
]

Коды ошибок:

400 - невалидное тело запроса
409 - файл уже существует
401 - пользователь не авторизован
500 - неизвестная ошибка

Папки

Получение информации о содержимом папки

GET /directory?path=$path

Ответ в случае успеха: 200 OK со следующим телом (appication/json). Коллекция ресурсов, лежащих в папке (не рекурсивно):

[
  {
    "path": "folder1/folder2/", // путь к папке, в которой лежит ресурс
    "name": "file.txt",
    "size": 123, // размер файла в байтах. Если ресурс - папка, это поле отсутствует
    "type": "FILE" // DIRECTORY или FILE
  }
]

Коды ошибок:

400 - невалидный или отсутствующий путь
401 - пользователь не авторизован
404 - папка не существует
500 - неизвестная ошибка

Создание пустой папки

POST /directory?path=$path

Ответ в случае успеха: 201 Created со следующим телом (appication/json). Ресурс созданной папки:

{
  "path": "folder1/folder2/", // путь к папке, в которой лежит ресурс
  "name": "folder3",
  "type": "DIRECTORY"
}

Коды ошибок:

400 - невалидный или отсутствующий путь к новой папке
401 - пользователь не авторизован
404 - Родительская папка не существует
409 - папка уже существует
500 - неизвестная ошибка

Работа с сессиями, авторизацией, регистрацией #

В предыдущем проекте мы хранили сессии в SQL базе данных, используя SessionMiddleware.

В этом проекте воспользуемся SessionMiddleware в связке с Redis.

SQL база данных #

В этом проекте студент самостоятельно разрабатывает структуру базы данных для хранения пользователей (файлы и сессии располагаются в других хранилищах). Предлагаю использовать Postgres.

Использовать поддержку токенов, базовой аутентификации, аутентификации OAuth и других методов аутентификации.

Важно помнить о создании необходимых индексов в таблице Users. Например, логин пользователя должен быть уникальным. Схема БД в этом проекте очень простая, но тем не менее рекомендую попрактиковаться с миграциями.

Хранилище файлов S3 #

Для хранения файлов будем пользоваться S3 - simple storage service. Проект, разработанный Amazon Cloud Services, представляет из себя облачный сервис и протокол для файлового хранилища. Чтобы не зависеть от платных сервисов Amazon в этом проекте, воспользуемся альтернативным S3-совместимым хранилищем, которое можно запустить локально - https://min.io/

Докер образ для локального запуска MinIO - https://hub.docker.com/r/minio/minio/
Для работы с протоколом S3 существует официальная библиотека от Amazon - boto3

Структура S3 хранилища #

В SQL мы оперируем таблицами, в S3 таблиц не существует, вместо этого S3 оперирует бакетами (bucket - корзина) с файлами. Чтобы понять что такое бакет, можно провести аналогию с диском или флешкой.

Внутри бакета можно создавать файлы и папки.

Для хранения файлов всех пользователей в проекте создадим для них бакет под названием user-files. В корне бакета для каждого пользователя будет создана папка с именем в формате user-${id}-files, где id является идентификатором пользователя из SQL базы.

Каждая из таких папок является корнем для хранения папок данного пользователя. Пример - файл docs/test.txt пользователя с id 1 должен быть сохранён в путь user-1-files/docs/test.txt.

Работа с S3 из Python #

Как было упомянуто выше, для работы с S3 воспользуемся AWS Python SDK - boto3. Необходимо будет научиться пользоваться этой библиотекой, чтобы:

Создавать файлы
Переименовывать файлы
“Переименовывать” папки. Насколько знаю в S3 нет такой операции, переименование папки по сути представляет собой создание папки под новым именем и перенос туда файлов
Удалять файлы

Фронтенд #

Для проекта написан одностраничный фронтенд на React, спасибо Андрею @MrShoffen - https://github.com/zhukovsd/cloud-storage-frontend/.

Демо фронтенда с мокнутным API (фронтенд отображает “фейковые” данные) - https://zhukovsd.github.io/cloud-storage-frontend/files/.

Основные страницы:

Содержимое корневой папки
Содержимое вложенной папки
Формы регистрации и авторизации доступны через пункт “Выход” в меню заголовка главной страницы

Интеграция фронтенда #

Собранное React приложение представляет собой набор статических файлов - https://github.com/zhukovsd/cloud-storage-frontend/tree/master/dist.

Самый простой способ интеграции - добавить эти файлы в ресурсы проекта, чтобы DRF раздавал их как статику.

Необходимо, чтобы точка входа в React приложение (index.html) была доступна по корневому адресу в запущенном приложении. Остальные файлы должны быть доступны по соответствующим относительным путям.

Эндпоинты API при этом будут существовать под общим путём /api. Пример - /api/auth/sign-up.

Альтернативный способ интеграции - Docker #

В случае, если есть желание отделить фронтенд от бека, можно раздавать статику React приложения через запущенный в Docker контейнере Nginx:

В файле public/config.js необходимо прописать адрес API бэкенда. Пример - http://localhost:8080
Пересобрать Docker образ из Dockerfile
Запустить контейнер вручную или через Docker Compose

Тесты #

Интеграционные тесты сервиса по работе с пользователями #

Как и в прошлом проекте, покроем тестами связку слоя данных с классами-сервисами, отвечающими за пользователей.

Предлагаю воспользоваться Testcontainers для запуска тестов в контексте полноценной (а не in-memory) базы данных. Для этого использовать библиотеку django-test-plus, которая включает в себя поддержку работы с контейнерами Docker для запуска тестов в контексте реальной базы данных. Это позволяет приблизить окружение тестов к рабочему окружению, и тестировать нюансы, специфичные для конкретных движков БД.

Примеры тест кейсов:

Вызов метода “создать пользователя” в сервисе, отвечающем за работу с пользователями, приводит к появлению новой записи в таблице users
Создание пользователя с неуникальным username приводит к ожидаемому типу исключения

Интеграционные тесты сервиса по работе с файлами и папками #

Опциональное задание повышенной сложности - покрыть тестами взаимодействие с сервисом хранения данных, работающим Minio.

Примеры тест кейсов:

Загрузка файла приводит к его появлению в bucket’е Minio в корневой папке текущего пользователя
Переименование, удаление файлов и папок приводит к ожидаемому результату
Проверка прав доступа - пользователь не должен иметь доступа к чужим файлам
Поиск - пользователь может находить свои файлы, но не чужие

Docker #

В данном проекте впервые воспользуемся Docker для удобного запуска необходимых приложений - SQL базы, файлового хранилища MinIO, Redis.

Необходимо:

Найти образы для каждого нужного приложения из списка выше
Написать Docker Compose файл для запуска стека с приложениями (по контейнеру для каждого)
Знать Docker Compose команды для работы со стеком

Как будет выглядеть работа с Docker:

Для работы над проектом запускаем стек из контейнеров
Уничтожаем или останавливаем контейнеры (с сохранением данных на volumes), когда работа не ведётся
По необходимости уничтожаем данные на volumes, если хотим очистить то или иное хранилище, запустить

Деплой #

Будем вручную деплоить приложение на удалённый сервер. Все остальные приложения этого проекта (SQL, MinIO) запускаем через Docker Compose.

Шаги:

В хостинг-провайдере по выбору арендовать облачный сервер на Linux
Установить Python, Docker
Скопировать на удалённый сервер Docker Compose файл для запуска Postgres, MinIO

Ожидаемый результат - приложение доступно по адресу http://$server_ip:8080/.

План работы над приложением #

Docker Compose - добавить Postgres, Redis
Django - с помощью django.contrib.auth реализовать регистрацию и авторизацию пользователей, хранить сессии в Redis
Интеграционные тесты для сервиса регистрации
Docker Compose - добавить MinIO
Django - интегрировать AWS Python SDK и научиться совершать операции с файлами в бакете, написать сервис, инкапсулирующий необходимые для приложения операции
Методы API для загрузки файлов и папок
Методы API для отображения файлов и навигации по структуре директорий, действия с файлами (удаление, переименование)
Методы API для поиска файлов
Интеграционные тесты для сервиса, отвечающего за работу с файлами и папками
Деплой

Ресурсы для работы над ошибками #

Готовый проект можете отправить мне на ревью - https://t.me/zhukovsd