Перейти к основному содержимому

Разбиение на фрагменты

На предыдущей странице вы записали небольшой счёт в INVOICES и прочитали обратно. Всё выглядело неделимым: один put, один get. Но размер сообщения NATS ограничен, а PDF счёта может быть гораздо больше. Как файл вообще помещается в хранилище сообщений?

Он не помещается в одно сообщение: хранилище разбивает его. Здесь рассмотрим фрагменты, их сборку при get и последствия прерывания put.

Объект разбивается на фрагменты​

Фрагмент — сообщение с частью объекта. При put хранилище не пытается поместить весь файл в сообщение. Оно последовательно читает байты и разделяет их по фиксированной границе — размеру фрагмента, записывая каждую часть отдельным сообщением. Счёт на 3 МБ становится последовательностью сообщений.

Размер по умолчанию — 128 КБ. На прошлой странице разбиение не требовало включения: небольшой счёт целиком помещался в один фрагмент, значительно меньше 128 КБ. Крупный файл пересекает границу и создаёт несколько фрагментов.

Сохраните счёт на 3 МБ и прочитайте число фрагментов:

#!/bin/bash
# Put a large invoice into the INVOICES bucket and watch it get split into
# chunks. The object is `invoice-ord_9x3m.pdf`, a 3 MB PDF for one Acme
# order. You do nothing special to enable chunking: put always splits the
# bytes at the chunk size (128 KB by default) and stores each slice as one
# message.
#
# `order-svc` would run this after a large multi-page invoice is generated.
nats object put INVOICES invoice-ord_9x3m.pdf

# Read the object's metadata. The `Chunks` field is the count of chunk
# messages the bytes were split into; `Size` is the reassembled byte size;
# `Digest` is the SHA-256 the client computed while storing.
#
# At the 128 KB default a 3 MB file lands in roughly 24 chunks.
nats object info INVOICES invoice-ord_9x3m.pdf

# Get it back. The client streams the chunks in order, reassembles them,
# and verifies the SHA-256 against the stored digest before handing you a
# single file; the server only stores and replays the chunk and metadata
# messages. You never reassemble anything yourself.
nats object get INVOICES invoice-ord_9x3m.pdf --output ./invoice-ord_9x3m.pdf

Так сохраняется invoice-ord_9x3m.pdf, крупный счёт заказа Acme. В выводе nats object info появится поле Chunks: число сообщений, на которые разбиты байты. При стандартных 128 КБ файл на 3 МБ занимает примерно 24 фрагмента.

Запрашивать фрагменты и работать с ними отдельно не нужно. Это внутренняя реализация размещения файла в журнале сообщений. Записанный и прочитанный объект содержит те же байты; разбиение происходит между этими операциями.

Get собирает и проверяет​

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

При сборке заново вычисляется хеш SHA-256 и сравнивается с записанным при put. На прошлой странице вы познакомились с ним как с проверкой целостности. Совпадение означает сохранность байтов. Если фрагмент потерян или повреждён, get завершается ошибкой вместо возврата обрезанного файла.

Эта проверка делает get безопасным, хотя данные передавались множеством сообщений. Хеш вычисляется для всего объекта: одного пропущенного или переставленного фрагмента достаточно для несовпадения и отказа get.

Путь такой: put отправляет фрагменты, затем метаданные; get читает метаданные, затем фрагменты и проверяет хеш.

Сообщение метаданных после фрагментов содержит имя, размер, хеш и число фрагментов. Другие поля — описания, заголовки, ссылки — рассматриваются на следующей странице. Пока важно, что фрагменты идут первыми, а метаданные завершают put.

Неудачный put не создаёт половину объекта​

Фрагменты публикуются последовательно, поэтому put занимает время. Разрыв сети или сбой клиента может прервать запись после части фрагментов. Что станет с уже полученными?

Метаданные записываются последними, поэтому прерванный put не создаёт доступного объекта. Без записи метаданных get сообщает об отсутствии имени, а не возвращает половину файла. Если клиент продолжает работать, он также очищает уже записанные части. Исключение — аварийное завершение процесса: очистка не выполняется, и фрагменты остаются бесхозными. Get их не видит, поскольку на них не указывают метаданные, но они занимают место до удаления по лимитам или возрасту бакета.

Каждый put получает новый NUID, уникальный идентификатор конкретной записи, отдельный от имени объекта. Им помечаются все фрагменты этой операции. При повторной записи одного имени, например исправленного счёта поверх черновика, новые фрагменты не пересекаются со старыми. Хранилище записывает их под новой идентичностью, переключает метаданные и удаляет прежние. Повторный put заменяет объект целиком, а не смешивает новые байты со старыми.

Получаемый объект не бывает частично записанным. Незавершённый put не оставляет доступного объекта, повторный не склеивает старые и новые данные. Вы получаете полный записанный объект либо ошибку get.

Выбор размера фрагмента​

Размер можно настроить для отдельного put, изменив число сообщений объекта:

#!/bin/bash
# Set the chunk size on a put and watch the chunk count change. The same
# 3 MB `invoice-ord_9x3m.pdf` splits into more or fewer messages depending
# on where you draw the split boundary. The `--chunk-size` flag takes a
# plain byte count, and these are re-puts over the existing object, so pass
# `--force` to skip the replace prompt.
#
# A small chunk size makes many messages. Here 64 KB (65536 bytes) roughly
# doubles the chunk count versus the 128 KB default — more per-message
# overhead.
nats object put INVOICES invoice-ord_9x3m.pdf --chunk-size 65536 --force
nats object info INVOICES invoice-ord_9x3m.pdf

# A larger chunk size makes fewer messages. Keep each chunk under the
# server's maximum payload (max_payload, 1 MB by default); a chunk larger
# than that is rejected and the put fails. Here 512 KB (524288 bytes) stays
# well under the limit.
#
# The full set of chunk-size options is documented in
# [Reference](/reference/). We only need the behavior here.
nats object put INVOICES invoice-ord_9x3m.pdf --chunk-size 524288 --force
nats object info INVOICES invoice-ord_9x3m.pdf

Тот же счёт на 3 МБ даёт больше сообщений при меньших фрагментах и меньше — при больших. Стандартные 128 КБ подходят большинству файлов; обычно менять их не требуется.

Все варианты настройки размера приведены в справочнике. Здесь достаточно поведения.

Подводные камни​

Для крупных объектов важны две ловушки: крайние размеры фрагментов и проверка целостности при get.

Крайние размеры фрагментов создают проблемы. Слишком маленькие превращают файл в тысячи сообщений. Каждый фрагмент несёт собственное оформление протокола — заголовки и маршрутизацию темы сверх байтов данных, поэтому растут накладные расходы и замедляются put и get. Слишком большой фрагмент превышает max_payload сервера (по умолчанию 1 МБ) либо меньший лимит сообщения базового потока, заданный оператором. Тогда сервер отклоняет сообщение и put завершается ошибкой, а не разбивает его иначе. Не меняйте размер ради одного теста производительности: 128 КБ подходит почти всем файлам и заметно ниже стандартного предела. При увеличении держите фрагменты меньше max_payload, описанного в разделе Настройка потока. За этим пределом put перестаёт сохранять данные.

Проверяйте результат get до использования байтов. Неудачный get не возвращает обрезанный файл: сначала убедитесь в успехе. Поскольку фрагменты публикуются асинхронно, непроверенный сбой put может привести к ошибке проверки при чтении. Отсутствующий фрагмент или несовпадение хеша вызывает ошибку вместо возврата. При отказе заново запишите объект из исходника, а не отправляйте неполный счёт. Не считайте put успешным, пока get не собрал и не проверил объект.

Используйте результат get только при успехе, при ошибке повторите put:

#!/bin/bash
# Always check the get result before you trust the bytes. A get reassembles
# the chunks and verifies the SHA-256 against the stored digest; if the
# stored object is incomplete (a put that failed mid-stream, or a chunk
# that never landed) the get errors instead of handing you a truncated file.
#
# `nats object get` exits non-zero on a failed reassembly or digest
# mismatch, so guard the next step on its exit code.
if nats object get INVOICES invoice-ord_9x3m.pdf --output ./invoice-ord_9x3m.pdf; then
echo "invoice retrieved and digest verified"
else
# The bytes are not safe to use. Re-put from the source and retry rather
# than shipping a partial invoice.
echo "get failed: incomplete object or digest mismatch, re-put required" >&2
exit 1
fi

Текущее состояние​

Теперь у вас есть:

  • Крупный invoice-ord_9x3m.pdf во множестве фрагментов в INVOICES с доступным счётчиком Chunks.
  • Модель put как разбиения и записи, get — как сборки и проверки.
  • Две гарантии: при обработанном отказе put частичные фрагменты очищаются, а новая идентичность повторного put исключает смешивание со старыми байтами.

Фрагменты содержат данные. Завершающие put метаданные содержат всё об объекте; это тема следующей страницы.

Что дальше​

Метаданные содержат имя, размер и хеш. Можно добавить описание, HTTP-подобные заголовки, произвольные пары ключ/значение и ссылки между объектами.

Переходите к странице Метаданные и ссылки.

См. также​