MyLab.FileStorage.Client
1.4.4
dotnet add package MyLab.FileStorage.Client --version 1.4.4
NuGet\Install-Package MyLab.FileStorage.Client -Version 1.4.4
<PackageReference Include="MyLab.FileStorage.Client" Version="1.4.4" />
paket add MyLab.FileStorage.Client --version 1.4.4
#r "nuget: MyLab.FileStorage.Client, 1.4.4"
// Install MyLab.FileStorage.Client as a Cake Addin
#addin nuget:?package=MyLab.FileStorage.Client&version=1.4.4
// Install MyLab.FileStorage.Client as a Cake Tool
#tool nuget:?package=MyLab.FileStorage.Client&version=1.4.4
MyLab.FileStorage (FS)
MyLab.FS
- файловое хранилище с прямым авторизованным доступом клиента.
Ознакомьтесь с последними изменениями в журнале изменений.
Обзор
MyLab.FS
(далее файловое хранилище) - сервис, предназначенный для обеспечения функций хранения в информационной системе с авторизованным доступом клиентов.
Сервис позволяет загружать, хранить и скачивать файлы. Есть методы доступа с авторизацией для клиентов и без авторизации - для компонентов серверного приложения.
API хранилища не разделено каким либо образом на предназначенное для сервера и - для клиента, т.к. вопросы организации доступа к HTTP-API не является задачей данного сервиса.
Файлы хранятся в файловой системе сервера, где развёрнуто файловое хранилище. Каждый файл представляет директория, путь к которой строится с использованием идентификатора файла.
Хранилище не обеспечивает резервирования, теневого копирования, кластеризацию и другие средства обеспечения целостности хранящихся данных. Для этих целей используйте сторонние решения.
Эта директория содержит файлы:
content.bin
- содержательная часть файла;metadata.json
- метаданные файла.
Ниже приведён пример метаданных файла:
{
"id": "94b721e7bbfe4109864dcd8bef70d48e",
"created": "2001-01-01 21:22:23",
"md5": "e807f1fcf82d132f9bb018ca6738a19f",
"filename": "doc.txt",
"length": 10000,
"labels": {
"owner": "user@host.com",
"sign": "b2xvbG8="
},
"ttlh": "2"
}
, где:
id
- уникальный идентификатор файла в формате;created
- дата и время появления файла в хранилище;md5
-MD5
хэш файла в форматеHEX
строки;filename
- имя файла;labels
- произвольные метки в формате ключ-значение, имеющие значение в предметной области приложения,ttlh
- время жизни файла в часах (установлено только, если было указано клиентом при создании загрузки).
Загрузка файла
Загрузка сервером
При необходимости передать файл клиенту, серверное приложение может загрузить файл в файловое хранилище путём межсервисного взаимодействия, используя методы загрузки файла без авторизации (просто указав идентификатор файла) и запросить токен скачивания, который передаст клиенту.
Загрузка серверным приложением осуществляется без авторизации и состоит из следующих шагов:
- запрашивает токен загрузки;
- отправляет файл частями, прикладывая токен загрузки;
- завершает загрузку, указав контрольную сумму, метаданные и приложив токен загрузки;
- получает метаданные загруженного файла и подписанный токен файла;
- при необходимости проверяет полученные данные;
- подтверждает, что файл получен целевым сервисом;
- применяет данные файла (например, сохраняет идентификатор файла).
Загрузка клиентом
Для загрузки файла клиентом, серверное приложение должно запросить у файлового хранилища токен загрузки и передать его этому авторизованному клиенту. Далее клиент загружает файл напрямую в файловое хранилище, прикладывая выданный токен. Таким образом право на загрузку файла выдаёт серверное приложение в соответствии со своими бизнес-правилами. Токен загрузки - JWT
токен с HMAC-SHA256
подписью.
Особый случай, когда первичной авторизацией клиента занимается прозрачное прокси. Например, если прокси проверяет в запросе, в заголовке Authorization наличие актуального токена. Это может считаться авторизацией и тогда просто прокинутый запрос клиента в файловое хранилище для создания токена загрузки можно считать соответствующим алгоритму целевого использования.
В результате загрузки файла, клиент получает токен файла - подписанные данные о файле. Токен файла - JWT
токен с HMAC-SHA256
подписью. Получив этот токен от клиента, серверное приложение проверяет подпись токена, время его действия, а так же другие реквизиты в соответствии со своим бизнес-правилами. Например, лимит по размеру. В завершении приложение подтверждает в файловом хранилище получение файла.
Для проверки подписи токена файла приложение должно разделять секрет с файловым хранилищем, которым оно подписывает токены документов. После проверки, серверное приложение применяет полученные данные в соответствии со своим бизнес-процессом.
Проверка токена файла
Протокол загрузки файла клиентом подразумевает завершающим действием передачу токена файла серверному приложению, для которого загружался файл. Токен файла клиент получает при завершении загрузки файла.
В свою очередь серверное приложение должно проверить токен перед тем, как применить полученные данные.
В большинстве случаев необходимо сохранить только идентификатор файла. Реже - имя файла, чтобы позже была возможность передавать на клиент, в том числе, и имя для отображения без необходимости обращаться в файловое хранилище за этим именем.
Проверка токена файла состоит из следующих шагов:
проверка подписи:
Токен файла -
JWT
-токен с подписью по алгоритмуHMAC-SHA256
. При формировании подписи используется бинарный ключ длиной не менее 128 бит. В качестве ключа удобно использовать (например, в конфигурации) строку длиной не менее 16 символов. Файловое хранилище использует отдельный ключ для подписи токенов файлов.проверка времени действия;
проверка назначения файла:
При начале загрузки, когда серверное приложение по инициативе авторизованного клиента запрашивает токен загрузки у файлового хранилища, есть возможность указать назначение файла - поле
purpose
. Это произвольное строковое значение, которое характеризует область применения файла. На деле это позволяет приложению-получателю определить правильность адресации загруженного файла.Например, если в приложении есть два сервиса:
- визуализация
XML
файла по схемеXML->HTML->PDF
(purpose = xml-vis
) - отправка сообщений другим пользователям с вложениями (
purpose = msg-att
).
И клиент загрузил XML файл для визуализации, но токен файла передал в сервис отправки сообщений, указав как токен файла вложения. В этом случае серверное приложение может проверить это значение в токене файла и отказать.
Если требуется один и тот же файл использовать для разных целей, необходимо использовать общую цель. Например
xml-vis+mail-att
. Тогда сервисы-получатели могут иметь список действующих целей для проверки, что цель из токена соответствует хотя бы одному варианту.- визуализация
проверка реквизитов файла:
У серверного приложения могут быть и другие требования к файлу. Например, может быть ограничение по размеру файла.
Кроме того, у файла есть набор меток
labels
в формате ключ-значение. Эти метки могут хранить любую информацию из предметной области прилоэения, в том числе необходимую для проверки загруженного файла. Например, там может быть указана электронная подпись, которую потребуется проверить.
Скачивание файла
Скачивание сервером
При необходимости получить файл, серверное приложение может скачать файл из файлового хранилища путём межсервисного взаимодействия, используя методы скачивания файла без авторизации (просто указав идентификатор файла).
Скачивание серверным приложением осуществляется без авторизации и заключается в запросе содержания файла по частям.
Скачивание клиентом
Для скачивания файла клиентом, серверное приложение должно запросить у файлового хранилища токен скачивания и передать его этому авторизованному клиенту. Далее клиент скачивает файл напрямую из файлового хранилища, прикладывая выданный токен. Таким образом право на скачивание файла выдаёт серверное приложение в соответствии со своими бизнес-правилами. Токен скачивания - JWT
токен с HMAC-SHA256
подписью.
Конфигурация
Конфигурация файлового хранилища может быть осуществлена как через файл конфигурации, так и через переменные окружения в соответствии со стандартными механизмами .NET.
Узел в конфигурации - FS
. Ниже приведён пример конфигурации через переменные окружения:
FS__TransferTokenSecret=1234567890123456
FS__FileTokenSecret=6543210987654321
Поля конфигурации:
Directory
- базовая директория для хранения файлов. По умолчанию - /var/fs/data;TransferTokenSecret
- ключ подписи токенов загрузки и скачивания. Обязательный параметр;FileTokenSecret
- ключ подписи токенов файлов. Обязательный параметр;UploadTokenTtlSec
- время жизни токена загрузки в секундах. По умолчанию - 1 час;DownloadTokenTtlSec
- время жизни токена скачивания в секундах. По умолчанию - 1 час;FileTokenTtlSec
- время жизни токена файла в секундах. По умолчанию - 1 час;UploadChunkLimitKiB
- максимальный размер загружаемой части файла вKiB
. По умолчанию - 0.5 MiB;DownloadChunkLimitKiB
- максимальный размер скачиваемой части файла вKiB
. По умолчанию - 0.5 MiB;StoredFileSizeLimitMiB
- максимальный размер файла для хранения вMiB
. По умолчанию - нет ограничения.
Ключ подписи (TransferTokenSecret
и FileTokenSecret
) - строка с произвольным текстом. Длина строки должна быть больше 16 символов. Приложение конвертирует эту строку в байты по кодировке UTF-8
и использует получившийся бинарный ключ для подписи токенов.
Cleaner
Обзор
Cleaner
- приложение - задача. Осуществляет чистку файлового хранилища. Активируется по http
-запросу:
POST /processing
Целевое использование - в паре с планировщиком задач.
Очистка хранилища - удаление устаревших файлов:
- если файл не подтверждён и существует больше указанного в конфигурации периода;
- если файл подтверждён и если при его создании было указано время жизни и существует более этого времени;
- если файл подтверждён и если при его создании не было указано время жизни и существует более указанного в конфигурации периода.
Удаление подтверждённых файлов, для которых не было указано время жизни при создании, опционально и настраивается в конфигурации. Используется для работы файлового хранилища в режиме хранилища временных файлов
.
Конфигурация
Узел конфигурации - Cleaner
.
Параметры конфигурации:
Directory
- базовая директория для хранения файлов. По умолчанию - /var/fs/data;LostFileTtlHours
- время жизни неподтверждённых файлов в часах. 1 час по умолчанию;StoredFileTtlHours
- время жизни подтверждённых файлов в часах. Неограниченно по умолчанию.
Пример конфигурации через переменные окружения:
Cleaner__Directory=/var/fs/data
Cleaner__LostFileTtlHours=1
Cleaner__StoredFileTtlHours=12
Развёртывание
В данном разделе рассмотрено развёртывание с использованием docker
контейнеров.
Ниже приведён пример docker-compose.yml
для развёртывания файлового хранилища:
version: '3.2'
services:
mylab-fs-api:
container_name: mylab-fs-api
image: ghcr.io/mylab-tools/fs-api:latest
volumes:
- fs_data: /var/fs/data
environment:
- FS__TransferTokenSecret=1234567890123456
- FS__FileTokenSecret=6543210987654321
mylab-fs-cleaner:
container_name: mylab-fs-cleaner
image: ghcr.io/mylab-tools/fs-cleaner:latest
volumes:
- fs_data: /var/fs/data
environment:
- Cleaner__LostFileTtlHours=1
volumes:
fs_data:
Клиент
Для разработки клиента на .NET
предусмотрена библиотека с контрактами API
сервиса файлового хранилища. Опубликовано в виде NuGet
пакета MyLab.FileStorage.Client.
Контракты
Контракты разработаны с использованием MyLab.ApiClient:
IFsFilesApiV1
- API доступа к фалам. Ключ конфигурацииfs-files
;IFsDownloadApiV1
- API Скачивания. Ключ конфигурацииfs-download
;IFsUploadApiV1
- API Загрузки. Ключ конфигурацииfs-upload
.
Файловый токен
В приложении, принимающем загруженный файл, требуется осуществлять проверку переданного токена файла. Эти функкции выполняет класс FileToken
из пространства имён MyLab.FileStorage.Client.Tools
.
Ниже приведён пример проверки и извлечения данных о загруженном файле:
StoredFileMetadataDto fileMetadata = null;
try
{
FileToken actualFileToken = FileToken.VerifyAndDeserialize(strFileToken, Secret);
fileMetadata = actualFileToken.FileMetadata;
}
catch (SecurityTokenValidationException e)
{
//Handle invalid file token
}
Метрики
Файловое хранилище и Cleaner предоставляют http-метрики по адресу /metrics
в формате OpenMetrics.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net6.0
- Microsoft.IdentityModel.Tokens (>= 6.25.0)
- MyLab.ApiClient (>= 3.20.30)
- System.IdentityModel.Tokens.Jwt (>= 6.25.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.