Файловый сервис Filator

Конфигурация хранилища вложений

На данный момент поддерживаются два способа хранения вложений: в базе данных и S3 хранилище. Хранилища конфигурируются значением в переменной окружения STORAGES_CONFIGURATIONS - представляющей собой строку JSON формата, содержащую в себе массив объектов конфигурации. Существует возможность архивации и удаления записей.

Объект конфигурации имеет следующие поля:

При хранении в базе данных содержимое вложения сохраняется в таблице attachment_blobs в столбце blob. Связь с таблицей вложений осуществляется по столбцу attachment_id - значение которого равно значению столбца uuid таблицы attachments. Что касается s3 - из параметров видно, что есть возможность сохранять вложения как в один bucket, так и автоматически их создавать (при значении true в use_dynamic_buckets).

• При значении false в use_dynamic_buckets - запрос сохраняется в bucket по пути <prefix>-<YYYY-MM-DD>/<hh-mm>/<uuid>, где prefix может быть получен из параметра запроса store_prefix.
• При его отсутствии используется значение, указанное в prefix.
• При значении true в use_dynamic_buckets запись будет происходить в bucket вида <prefix>-<YYYY-MM-DD> по пути <hh-mm>/<uuid>

Пример конфигурации:

[
  {
    "name": "db",
    "type": "db",
    "readonly": true
  },
  {
    "name": "s3",
    "type": "s3",
    "readonly": false,
    "use_dynamic_buckets": false,
    "endpoint": "http://localhost:9000",
    "access_key": "minioadmin",
    "secret_key": "minioadmin",
    "bucket": "test",
    "prefix": "filator",
    "open_timeout": 5,
    "read_timeout": 15,
    "ssl_verify_peer": true,
    "retry_limit": 3
  },
  {
    "name": "s3_second",
    "type": "s3",
    "readonly": false,
    "use_dynamic_buckets": true,
    "endpoint": "http://localhost:59000",
    "access_key": "minioadmin",
    "secret_key": "minioadmin",
    "bucket": "second-test",
    "prefix": "filator"
  }
]

Архивация и удаление

Несмотря на то, что сами данные объектных файлов могут храниться в S3-совместимом хранилище, связующая информация (записи в таблице attachments) занимает много места. При это профиль нагрузки данного сервиса предполагает полное отсутствие исторических чтений - файлы (вложения или XML-логи из СМЭВ), загруженные сюда, никогда не будут читаться после определённого времени. Исключение составляет ручной поиск файлов в процессе разрешения инцидентов. Из-за такого специфического профиля нагрузки в сервисе реализован механизм архивации и удаления данных:

1. из системы выгружается ZIP-архив, содержащий все данные из таблицы attachments старше указанной даты. Например старше 3х месяцев;
2. этот ZIP-архив подлежит загрузке в надёжное хранилище для длительного хранения;
3. заархивированные данные удаляются из БД.

HTTP-API сервиса filator

Имеется API, позволяющее взаимодействовать с сервисом filator, а именно:

1. Загружать файл в сервис
2. Получать файл из сервиса
3. Обновлять уже существующий файл в сервисе
4. Получать метаданные (в виде JSON) по файлу в сервисе
5. Архивировать и удалять данные

Загрузка файла в сервис

Параметры для запроса

• Endpoint: /attachments
• Method: POST
• Путь к файлу: /path/to/file

Описание curl запроса для загрузки файла в сервис

curl -X POST -F "body=@/path/to/file" http://filator/attachments

Где:

Пример curl запроса для загрузки файла в сервис (с заполненными параметрами)

curl -X POST -F "body=@/tmp/pic.png" http://filator/attachments

Ответ в случае успешного приема файла сервисом

{
    "uuid": "26956714ab02f3dcf12dc53c15837866bc2e438f2fd46b682582c83945d1ce08",
    "checksum": "e150a1ec81e8e93e1eae2c3a77e66ec6dbd6a3b460f89c1d08aecf422ee401a0",
    "created_at": "2021-12-11T15:47:26.570+03:00",
    "tags": [],
    "metadata": {},
    "delete_at": "2021-12-12T15:47:26.555+03:00",
    "mime_type": "text/plain",
    "filename": "data.txt",
    "store": "s3",
    "identifier_in_store": "filator-2021-12-11/15-47/26956714ab02f3dcf12dc53c15837866bc2e438f2fd46b682582c83945d1ce08"
}

Пример запроса в powershell

$resp = Invoke-WebRequest -Uri http://172.22.1.13:3000/attachments -Method Post -Form @{body=Get-Item -Path '/tmp/file'; "metadata[test]"="123"; delete_at="2022-04-04 23:22:32"} -Headers @{'X-METADATA-TEST2'=123}
$resp

В $resp содержится следующее

StatusCode        : 201
StatusDescription : Created
Content           : {"uuid":"211b4a9df4820eb1d14dbf2dd343943519f251f6576b684249fae33309908597","checksum":"e150a1ec81e8e93e1eae2c3a77e66ec6dbd6a3b460f89c1d08aecf422ee401a0","created_at":"2021-12-11T15:5
                    2:46.996+03:00","t…
RawContent        : HTTP/1.1 201 Created
                    Transfer-Encoding: chunked
                    Connection: keep-alive
                    Status: 201 Created
                    Cache-Control: must-revalidate, max-age=0, private
                    Referrer-Policy: strict-origin-when-cross-origin
                    X-Permitt…
Headers           : {[Transfer-Encoding, System.String[]], [Connection, System.String[]], [Status, System.String[]], [Cache-Control, System.String[]]…}
Images            : {}
InputFields       : {}
Links             : {}
RawContentLength  : 466
RelationLink      : {}

В свойстве Content

{
  "uuid": "211b4a9df4820eb1d14dbf2dd343943519f251f6576b684249fae33309908597",
  "checksum": "e150a1ec81e8e93e1eae2c3a77e66ec6dbd6a3b460f89c1d08aecf422ee401a0",
  "created_at": "2021-12-11T15:52:46.996+03:00",
  "tags": [],
  "metadata": {
    "test2": "123",
    "test": "123"
  },
  "delete_at": "2022-04-04T23:22:32.000+03:00",
  "mime_type": "text/plain",
  "filename": "data.txt",
  "store": "s3",
  "identifier_in_store": "filator-2021-12-11/15-52/211b4a9df4820eb1d14dbf2dd343943519f251f6576b684249fae33309908597"
}

Получение файла из сервиса

Параметры для запроса

• Endpoint: /attachments
• Method: GET
• Params: :uuid

Описание curl запроса для получения файла из сервиса

curl http://filator/attachments/:uuid > exchange_logs.zip

Где:

Пример curl запроса для получения файла из сервиса (с заполненными параметрами)

curl http://filator/attachments/5abe72ffb237db8f98dc825dfb72d2ce59566492f1bafe3f4266df0a5c37d3a6 > exchange_logs.zip

Ответ в случае наличия файла в сервисе и его отдачи

В ответ будет возвращен бинарный вывод содержимого файла, который необходимо сохранить. В примере это показано как > exchange_logs.zip

Ответ в случае отсутствия в сервисе файла с соответствующим uuid

{
  "status":"error",
  "msg":"Not found"
}

Обновление загруженного в сервис файла

Параметры для запроса

• Endpoint: /attachments
• Method: PUT
• Params: :uuid
• Путь к файлу: /path/to/file

Описание curl запроса обновления существующего файла в сервисе

curl -X PUT -F "body=@/path/to/file" http://filator/attachments/:uuid

Где:

Пример curl запроса для обновления уже существующего файла в сервисе

curl -X PUT -F "body=@/tmp/pic2.png" http://filator/attachments/5abe72ffb237db8f98dc825dfb72d2ce59566492f1bafe3f4266df0a5c37d3a6

Ответ в случае наличия файла в сервисе и его успешного обновления

{
  "uuid": "5abe72ffb237db8f98dc825dfb72d2ce59566492f1bafe3f4266df0a5c37d3a6",
  "checksum": "91158455354333f936b0b8b671d9ca06d3fca5a6bf3dc2f591e99d352057c0ea",
  "created_at": "2021-12-11T14:59:16.614+03:00",
  "tags": [],
  "metadata": {},
  "delete_at": "2021-12-12T14:59:16.600+03:00",
  "mime_type": "image/png",
  "filename": "pic2.png",
  "store": "db",
  "identifier_in_store": "424c5ea96eb6ce9941601a78f8395180b8e6a0bd2769a2f0a7bb49871e2669e9"
}

Ответ в случае отсутствия файла с переданным uuid в сервисе

Будет создан файл, ему будет присвоен переданный uuid. Ответ в таком случае не будет отличаться от операции загрузки файла в сервис:

{
  "uuid":"5abe72ffb237db8f98dc825dfb72d2ce59566492f1bafe3f4266df0a5c37d3a6",
  "checksum":"91158455354333f936b0b8b671d9ca06d3fca5a6bf3dc2f591e99d352057c0ea",
  "created_at":"2021-09-08T11:49:00.103+03:00",
  "tags":[],
  "metadata": {},
  "delete_at": null,
  "mime_type": "image/png",
  "filename":"pic2.png",
  "store": "s3",
  "identifier_in_store": "filator-2021-12-11/15-58/5abe72ffb237db8f98dc825dfb72d2ce59566492f1bafe3f4266df0a5c37d3a6"
}

Получение метаданных (в виде JSON) из сервиса

Параметры для запроса

• Endpoint: /attachments
• Method: GET
• Params: :uuid

Описание curl запроса для получения метаданных файла из сервиса

curl http://filator/attachments/:uuid.json

Где:

Пример curl запроса для получения метаданных файла из сервиса

curl http://filator/attachments/5abe72ffb237db8f98dc825dfb72d2ce59566492f1bafe3f4266df0a5c37d3a6.json

Ответ в случае наличия в сервисе файла с переданным uuid

{
  "uuid":"5abe72ffb237db8f98dc825dfb72d2ce59566492f1bafe3f4266df0a5c37d3a6",
  "checksum":"91158455354333f936b0b8b671d9ca06d3fca5a6bf3dc2f591e99d352057c0ea",
  "created_at":"2021-09-08T10:57:27.247+03:00",
  "tags":[],
  "metadata": {},
  "delete_at": null,
  "mime_type": "image/png",
  "filename":"pic2.png",
  "store": "db",
  "identifier_in_store": "5abe72ffb237db8f98dc825dfb72d2ce59566492f1bafe3f4266df0a5c37d3a6"
}

Ответ в случае отсутствия в сервисе файла с переданным uuid

{
  "status":"error",
  "msg":"Not found"
}

Архивация и удаление данных

Чтобы избежать непреднамеренной потери информации, архивация и удаление реализованы транзакционно. Процесс выполнения:

1. создание транзакции на удаление определённых данных;
2. получение архива в рамках данной транзакции;
3. загрузка архива в надёжное хранилище - ⚠️ производится оператором самостоятельно ⚠️;
4. закрытие транзакции - реальное удаление данных из БД;

Архивация и удаление данных: создание транзакции

Параметры для запроса

• Endpoint: /attachments/archive/tx
• Method: POST

Возможные параметры запроса:

Пример curl запроса

curl -X POST http://filator/attachments/archive/tx

Пример ответа:

{
  "uuid": "30646c049500f5f94d077565f25cd14a0d79b2cb5ca4bde2cab587e5cb32146e",
  "ctx": {
    "date": "2022-09-01T00:00:00+03:00"
  },
  "commit": null,
  "created_at": "2022-12-01T16:24:21.961+03:00",
  "updated_at": "2022-12-01T16:24:21.961+03:00"
}

Архивация и удаление данных: получение архива

Параметры для запроса

• Endpoint: /attachments/archive/:uuid
• Method: POST

Возможные параметры запроса:

Пример curl запроса

curl -X GET http://filator:3000/attachments/archive/30646c049500f5f94d077565f25cd14a0d79b2cb5ca4bde2cab587e5cb32146e -o /tmp/archive.zip

Пример wget запроса

wget http://filator:3000/attachments/archive/89fb4474c1c1ed7f9f404bcc252ee26ee2d7a0cb7d52fafb4d905618ba27543b --content-disposition

Пример ответа:

--2022-12-01 16:32:43--  http://filator:3000/attachments/archive/89fb4474c1c1ed7f9f404bcc252ee26ee2d7a0cb7d52fafb4d905618ba27543b
Распознаётся filator 127.0.0.1
Подключение к filator|127.0.0.1|:3000... соединение установлено.
HTTP-запрос отправлен. Ожидание ответа… 200 OK
Длина: нет данных [text/html]
Сохранение в: «attachments_le2022-09-01T00:00:00+03:00.zip»

2022-12-01 16:32:45 (939 MB/s) - «attachments_le2022-09-01T00:00:00+03:00.zip» сохранён [491722]

Архивация и удаление данных: закрытие транзакции

При успешном выполнении данной функции данные будут физически удалены из БД.

Параметры для запроса

• Endpoint: /attachments/archive/:uuid
• Method: DELETE

Возможные параметры запроса:

Пример curl запроса

curl -X DELETE http://filator/attachments/archive/30646c049500f5f94d077565f25cd14a0d79b2cb5ca4bde2cab587e5cb32146e

Пример ответа:

{
  "uuid": "30646c049500f5f94d077565f25cd14a0d79b2cb5ca4bde2cab587e5cb32146e",
  "ctx":{
    "date": "2022-09-01T00:00:00+03:00",
    "count": 46
  },
  "commit": "Файл загружен в minio в папку \"важные бэкапы\"",
  "created_at": "2022-12-01T15:04:40.868+03:00",
  "updated_at": "2022-12-01T15:04:54.734+03:00"
}