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

Параметр Значение
Название filator
Описание Временное файловое хранилище с HTTP-интерфейсом. Предназначено для передачи файлов между сервисами в процессе работы. Устаревшие файлы удаляются через некоторое время.
Техническая информация Представляет собой web-приложение, реализованное на языке Ruby (Ruby on Rails)
Для взаимодействия использует HTTP порт 80
Имя БД по умолчанию: aggredator-filator Данные хранятся в БД или в S3
Используемые порты (протоколы) 80 (HTTP)
Требуется доступ (порт) db (5432)
redis (6379)
stand-alone нет

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

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

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

Имя поля Тип хранилища Значение по умолчанию (если есть) Описание
name все   Идентификатор хранилища. Информация о хранилище сохраняется в blob_data в поле storage и содержит в себе данное значение. Для хранилища типа база данных допустимо использование только имени db
type все   Тип хранилища. Допустимые значения: db, s3
readonly все   Флаг, определяющий что хранилище используется только для чтения. Для запуска приложения должно быть хотя бы одно не readonly хранилище
endpoint s3   Адрес обращения к S3
access_key s3   Логин доступа к S3
secret_key s3   Пароль пользователя S3
use_dynamic_buckets s3 false Признак создания и использования новых bucket`ов
bucket s3   Bucket, в который будет происходить запись, если use_dynamic_buckets равно false
prefix s3   Префикс, используемый для генерации путей или имени bucket`а (при use_dynamic_buckets равном true)
region s3 region Регион
open_timeout s3 5 Таймаут (в секундах) на открытие соединения
read_timeout s3 15 Таймаут (в секундах) на чтение
ssl_verify_peer s3 true Признак выполнения ssl проверок
retry_limit s3 3 Количество повторных попыток загрузить файл в хранилище

При хранении в базе данных содержимое вложения сохраняется в таблице 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

Где:

параметр описание обязательный
/path/to/file путь к файлу, который должен быть загружен в сервис +
delete_at Временная метка, при достижении которой файл должен быть удален. В случае указания значения never - не будет использовано значение по умолчанию, файл не будет удален -
metadata Метаданные (также могут быть указаны в заголовках с префиксом X_METADATA_) -

Пример 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

Где:

параметр описание обязательный
:uuid 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

Где:

параметр описание обязательный
:uuid uuid файла, который был ранее загружен в сервис +
/path/to/file путь к файлу, который должен заменить существующий файл в сервисе +

Пример 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

Где:

параметр описание обязательный
:uuid uuid файла, который был ранее загружен в сервис +

Пример 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

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

параметр описание обязательный пример
date Дата, все данные ДО которой будут заархивированы и в дальнейшем удалены.
По умолчанию: берётся дата три месяца назад
- 20220101

Пример 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

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

параметр описание обязательный пример
uuid Идентификатор открытой ранее транзакции + 30646c049500f5f94d077565f25cd14a0d79b2cb5ca4bde2cab587e5cb32146e

Пример 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

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

параметр описание обязательный пример
uuid Идентификатор открытой ранее транзакции + 30646c049500f5f94d077565f25cd14a0d79b2cb5ca4bde2cab587e5cb32146e
message Коментарий к закрытию транзакции. Например, адрес "холодного" хранилища. + Файл загружен в minio в папку "важные бэкапы"

Пример 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"
}
  • Файловый сервис Filator
  • Конфигурация хранилища вложений
  • Архивация и удаление
  • HTTP-API сервиса filator
  • Загрузка файла в сервис
  • Параметры для запроса
  • Описание curl запроса для загрузки файла в сервис
  • Пример curl запроса для загрузки файла в сервис (с заполненными параметрами)
  • Ответ в случае успешного приема файла сервисом
  • Пример запроса в powershell
  • Получение файла из сервиса
  • Параметры для запроса
  • Описание curl запроса для получения файла из сервиса
  • Пример curl запроса для получения файла из сервиса (с заполненными параметрами)
  • Ответ в случае наличия файла в сервисе и его отдачи
  • Ответ в случае отсутствия в сервисе файла с соответствующим uuid
  • Обновление загруженного в сервис файла
  • Параметры для запроса
  • Описание curl запроса обновления существующего файла в сервисе
  • Пример curl запроса для обновления уже существующего файла в сервисе
  • Ответ в случае наличия файла в сервисе и его успешного обновления
  • Ответ в случае отсутствия файла с переданным uuid в сервисе
  • Получение метаданных (в виде JSON) из сервиса
  • Параметры для запроса
  • Описание curl запроса для получения метаданных файла из сервиса
  • Пример curl запроса для получения метаданных файла из сервиса
  • Ответ в случае наличия в сервисе файла с переданным uuid
  • Ответ в случае отсутствия в сервисе файла с переданным uuid
  • Архивация и удаление данных
  • Архивация и удаление данных: создание транзакции
  • Параметры для запроса
  • Пример curl запроса
  • Архивация и удаление данных: получение архива
  • Параметры для запроса
  • Пример curl запроса
  • Пример wget запроса
  • Архивация и удаление данных: закрытие транзакции
  • Параметры для запроса
  • Пример curl запроса
  • Подавай заявку сейчас

    Оставьте свои контактные данные и наш менеджер свяжется с вами в ближайшее время