IPFS: профиль повторяемого импорта
Одинаковые исходные файлы могут дать разные корни, если инструменты используют разные настройки импорта. Для библиотеки нужен профиль: документ, который определяет преобразование подготовленного каталога в блоки. В уроке сформулируем такой договор и отличим воспроизводимость содержания от воспроизводимости UnixFS-представления.
Программа импорта не устанавливается и не запускается. Мы не утверждаем, что выбранные параметры уже дали определённый CID. Результат — заполненная модель профиля, которую позже можно применить и сверить на изолированных данных.
Две цели воспроизводимости
Первая цель — одинаковые исходные байты. Если сборка Markdown на двух компьютерах добавляет разное время генерации в HTML, набор уже отличается до IPFS. Настройки импортёра не исправят эту разницу. Поэтому сначала фиксируем правила получения файлов и исключаем случайные переменные.
Вторая цель — одинаковое представление блоков. Даже при совпавших файлах можно выбрать разный размер частей, форму DAG, кодеки листьев или метаданные. Корневые блоки тогда не совпадут. Для воспроизводимого корня нужны оба договора.
В библиотеке сохраняем источник Markdown отдельно от готового выпуска. Исходник полезен для редактирования, а объявленная версия связывается с точными выходными файлами. Исправление генератора может изменить HTML без правки текста; это всё равно новый набор байтов.
Поля профиля
Запишем собственную модель:
{
"profileId": "library-unixfs-v1",
"cidVersion": 1,
"hash": "sha2-256",
"chunking": "fixed-262144",
"rawLeaves": true,
"directoryWrapping": true,
"fileMetadata": "normalized",
"inputOrder": "documented"
}Это редакционный документ, не буквальная конфигурация любого клиента. Ключи описывают решения, которые нужно сопоставить с аргументами выбранной реализации. Нельзя передать этот JSON в произвольную функцию и ожидать поддержку всех значений.
Размер части 262 144 выбран как понятный профиль учебного примера, а не универсальная оптимизация. Для крупных видео или изменяющихся архивов могут потребоваться другие решения. Изменение профиля создаёт новую версию представления и требует сохранения прежних настроек для восстановления старого корня.
Кодеки и дерево
Сырые листья означают определённый способ хранения частей без дополнительной оболочки соответствующего типа. Родительские структуры всё равно связывают их по правилам. Поэтому наличие rawLeaves=true не означает, что весь каталог стал одним сырым блоком.
Форма дерева определяет связи и может влиять на доступ к диапазонам, потоковое чтение и повторное использование. В маленьком примере различие иногда незаметно, но профиль должен назвать выбранную стратегию. Иначе второй инструмент применит собственные значения по умолчанию.
Версия CID и текстовая база также фиксируются для удобной нормальной формы. При этом текстовое преобразование одного CID не следует путать с повторным импортом. Профиль описывает и содержание блоков, и способ представления результата в досье.
Метаданные файлов
Исходная файловая система может иметь режимы и времена изменения, отличающиеся на двух компьютерах. Если импортёр сохраняет их в структурных блоках, корень меняется. Для учебного выпуска определяем, какие метаданные необходимы и как они нормализуются.
Не удаляем полезные поля без понимания требований. Например, архив исходников и готовый статический сайт могут иметь разные задачи. Но для публичного учебного набора случайное время локальной записи редко является частью содержательного договора. Решение фиксируется один раз в профиле, а не принимается заново перед каждым выпуском.
Имена файлов и их регистр тоже входят в структуру. На одной системе Index.html и index.html могут вести себя иначе, чем на другой. Выпуск использует согласованный набор имён и относительных ссылок. Unicode-имена требуют отдельного соглашения о точных байтах и нормализации, если такая нормализация применяется.
Совместимость инструментов
Helia и Kubo могут поддерживать схожие функции, но не нужно обещать совпадение любого результата по умолчанию. Читатель сопоставляет профиль с конкретными аргументами и закреплёнными версиями. Если один инструмент не поддерживает требуемый параметр, профиль пересматривается явно либо выбирается другой маршрут.
В досье сохраняем версию импортёра и зависимости, когда они будут выбраны для исполнения. Ссылка на текущий README помогает исследованию, но не заменяет lockfile конкретного проекта. В этой серии клиентские пакеты не устанавливаются, поэтому мы не выдаём неизвестную локальную версию за проверенную.
Проверку будущего импорта строим на маленьком контрольном каталоге и его заранее сохранённой описи. Два результата сравниваются по корню, составу блоков и восстановленным файлам. Совпадение только итогового текста не доказывает совпадение структуры, а совпадение объявленного корня без получения зависимостей не доказывает полноту хранения.
Разобрать несовпадение двух компьютеров
Редактор и хранитель импортируют один учебный набор и получают разные корни. Сначала сравнивают описи исходных файлов: относительные пути, точные размеры и файловые контрольные суммы. Если различается HTML, проблема возникла до UnixFS. Например, генератор вставил локальную дату или системный путь. Переустановка IPFS-клиента не исправит такую причину; нужно заново определить подготовленные байты и оформить исправленный выпуск.
Если описи совпали, переходят к профилям. Один импортёр мог сохранить время изменения файлов, другой — исключить его. Восстановленное содержимое выглядит одинаково, но структурные блоки различаются. Другой возможный источник — дополнительные оболочки каталога: один результат адресует непосредственно папку с index.html, второй адресует родителя, содержащего эту папку. Оба корня могут быть корректными, но отвечают разным путям и не являются взаимозаменяемой строкой в досье.
Сверка должна перечислять именно применённые параметры, включая поведение текущей версии импортёра. Редакционный JSON из урока сообщает намерение; фактическая конфигурация показывает его реализацию. Если ключ не поддержан или проигнорирован, имя профиля не доказывает соблюдение договора. Поэтому будущий протокол подготовки сохраняет явное сопоставление полей и аргументов выбранного инструмента, а также его закреплённую версию.
Для третьей редакции библиотека может сознательно изменить профиль. Тогда старый каталог не переписывают под новым корнем с прежним обозначением представления. Сохраняют исходный профиль для восстановления старых выпусков и вводят новый идентификатор профиля. Читателю полезно различать правку содержания и изменение упаковки. Архивисту нужны оба значения: они объясняют, почему файловые отпечатки совпадают, а корни различаются. Такое описание позволяет расследовать расхождения без обещания, что любые два клиента всегда импортируют файлы одинаково.
Изменение профиля
Во втором выпуске редакция может сохранить текст, но выбрать другой профиль для больших изображений. Тогда фиксируем новый profileId и не называем новый корень подменой старого. У читателя остаётся возможность восстановить прежнее представление по прежнему договору.
Документация параметров находится в спецификации UnixFS и описании CID-профилей. Результат урока — договор импорта, который дополняет точные байты. Он делает ожидаемое совпадение корня проверяемым утверждением, а не надеждой на одинаковые настройки двух компьютеров.