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

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

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

Go - std lib, http, пакеты, интерфейсы
Go modules
Backend
- Echo http router или любой другой роутер
- HTTP - заголовки, понимание методов
- REST, Swagger, Upload файлов
- Cookies, cессии
- Upload файлов, обработка multipart-форм
Базы данных
- PostgreSQL
- Squirrel или обычный драйвер к бд
- Миграции
- Представление о NoSQL хранилищах
Frontend - HTML/CSS, Bootstrap
Тесты - юнит и интеграционные тесты (testify, testcontainers-go)
- моки HTTP и S3-клиентов
Docker - контейнеры, образы, volumes, Docker Compose
Деплой - облачный хостинг, командная строка Linux

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

Практика проектирования многослойной Go-архитектуры с чётким разделением ответственности (handlers - services - repositories/storage)
Практика с Docker и Docker Compose
Первый проект, где студент самостоятельно разрабатывает структуру БД
Знакомство с NoSQL хранилищами - S3 для файлов, Redis для сессий
Интеграция по REST с одностраничным frontend приложением на React

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

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

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

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

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

REST API #

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

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

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

Тело ответа:

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

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

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

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 - неизвестная ошибка

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

GET /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 - неизвестная ошибка

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

Необходимо реализовать Middleware для работы с юзерами, которая будет получать данные из cookies. Будем хранить сессии юзеров в redis.

Swagger #

Задачи:

Написать Swagger документацию по проекту
Сгенерировать модели запросов и ответов с помощью инструментов кодогенарции: oapi-codegen, openapi-generator
Интегрировать полученный код в проект
Проверить работоспособность методов API через Swagger UI

Rate Limiting #

Необходимо реализовать библиотеку на основе Redis для механизма rate limiting (ограничения числа запросов), интегрируемой в middleware. Библиотека должна поддерживать гибкую настройку лимитов (запросов в секунду/минуту), работать с учётом идентификатора клиента (IP или токена), и использовать Redis с атомарными операциями (например, INCR + EXPIRE, или SET с NX и GET). Конфигурация лимитов — через параметры при инициализации, с возможностью указать разные правила для разных эндпоинтов (например, /auth/sign-in — 5 запросов/минуту/IP, остальное — 100/минуту/IP). Middleware должен возвращать 429 Too Many Requests при превышении лимита и корректно устанавливать заголовки X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After.

Реализация должна использовать алгоритм sliding window (а не fixed window), чтобы избежать всплесков запросов на границах интервалов и обеспечить более плавное и справедливое ограничение. Библиотека обязана быть потокобезопасной, так как будет использоваться в конкурентной среде HTTP-сервера — состояние не должно храниться в памяти, вся логика счёта и синхронизации должна выполняться атомарно на стороне Redis, pipeline-операции с гарантией атомарности.

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

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

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

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

Миграции #

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

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

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

Докер образ для локального запуска MinIO - https://hub.docker.com/r/minio/minio/
Для работы с протоколом S3 воспользуемся любой s3-совместимой библиотекой, например https://github.com/minio/minio-go

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

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

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

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

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

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

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

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

Фронтенд #

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

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

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

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

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

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

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

Тесты #

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

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

Вместо с предлагаю воспользоваться testcontainers-go для запуска тестов в контексте полноценной (а не in-memory) базы данных. Это позволяет приблизить окружение тестов к рабочему окружению, и тестировать нюансы, специфичные для конкретных движков БД.

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

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

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

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

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

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

Docker #

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

Необходимо:

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

Деплой #

Будем деплоить чреез docker-compose. Приложение и вся инфраструктура (PostgreSQL, Redis, MinIO) разворачиваются через единый docker-compose.yml, включающий:

один сервис для Go-бэкенда (сборка из Dockerfile),
три сервиса внешних зависимостей

Шаги:

Локально собрать и протестировать образ приложения
В хостинг-провайдере по выбору арендовать облачный сервер на Linux
установить Docker, docker-compose
Используя git склонировать проект
Запустить приложение с помощью docker-compose

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

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

Docker Compose - добавить Postgres
Go - реализовать auth middleware и методы для регистрации и авторизации пользователей
Интеграционные тесты для сервиса регистрации
Docker Compose - добавить MinIO
S3:
- интегрировать s3-совместимую библиотеку
- написать FileStorage интерфейс и реализацию (MinIOStorage)
Реализовать загрузку файлов и папок
Реализовать методы API для получения файлов и папок, действия с файлами (удаление, переименование)
Поиск файлов - сервис, контроллер и методы API
Интегрировать фронтенд
(Опционально) интеграционные тесты для сервиса, отвечающего за работу с файлами и папками
Docker Compose - добавить Redis
Собрать образ Go приложения и протестировать систему
Деплой

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

Реализации проекта другими студентами и ревью этих реализаций
Чеклист для самопроверки с типовыми ошибками (в конце страницы)
Присылайте законченные проекты в чат, добавляю их в список, сообщество делает ревью проектов

Чеклист для самопроверки #

❗️Спойлеры: советую не читать этот список до того момента, пока не допишете первую самостоятельную работающую версию проекта❗️

Функциональные проблемы:

Несоответствие формата API требуемому, особенно в вопросах обработки ошибок
Ошибки валидации имён файлов и папок
Затирание файлов и папок при переименовании или перемещении (пример - папка с файлами 1 и 2, при переименовании 2 в 1, оригинальный файл 1 будет утерян)
Битые файлы и архивы папок при скачивании
Возможность попасть в несуществующую папку, вместо того чтобы увидеть ошибку 404
Возможность найти файл другого пользователя через поиск, или скачать его (через ручное формирование ссылки)
Низкие лимиты на максимальный размер загружаемого файла или папки

“Протекание” деталей реализации хранения файлов в Minio в пользовательский интерфейс, REST ответы, код контроллеров:

В пути к файлу содержится его корневая папка user-${id}-files
Не скрытая в сервисах, отвечающих за работу с Minio работа с пустыми папками (через, например, создание 0-byte файла с особым именем)