PUBLICATION, DEPRECATION и TOMBSTONE — Edge-высказывания, фиксирующие публикацию версии документа, рекомендацию прекратить её использование и удаление; эта страница задаёт также спецификацию документа списка версий, записываемого этими Edge (Codec 0x0B8L~0x0BAL).

ПунктЗначение
ИмяDEPRECATION (BIND документа спецификации DEPRECATION)
TAG ID0x0B9L
Codec ID0x00000B90
Документ спецификации0x00000000/codecs/0x00000B90/ (цель DECLARE 0B90)
Раздел5 0101 (Edge-высказывание), смещение C внутри раздела = 25
KindEdge · семейство: высказывание, группа: прочее
TAG WORD0000 1011 1001 LLLL (000K KKKC CCCC LLLL)
Описание в индексеDeprecate опубликованной версии. DOC-POINTER
Сторона Hugoedge/publication.md (эта страница рассматривает также PUBLICATION и TOMBSTONE)

Поля (документ спецификации)

Порядок FIELD в документе — это порядок полей Payload (документ спецификации Codec). Edge Id у Edge не объявляется через FIELD.

ПорядокПоле (BIND)FIELDШиринаПринимаемый формат (CODEC)ENUM
1doc#2запись0410 DOC-POINTER, 0420 CODEC-POINTER

Это Edge-высказывания, фиксирующие публикацию, deprecate и удаление документа, и спецификация документа списка версий, записываемого этими Edge. Они задают формат списка версий из раздела адрес публикации и список версий.

Коды

CodecИмяPayload
0x0B8LPUBLICATIONEdge Id, DOC-POINTER, хеш содержимого
0x0B9LDEPRECATIONEdge Id, DOC-POINTER
0x0BALTOMBSTONEEdge Id, DOC-POINTER, категория причины
  • Три кода встроены в декодер (слой 0). Список версий интерпретируется без обращения к кодовой книге.
  • Подформатов (TAG для Codec) нет. Правило Edge о том, что первый элемент Payload — Edge Id, соблюдается без изменений.

Раскладка

TAG WORD          Edge, Codec 0x0B8L / 0x0B9L / 0x0BAL
[Length, расширяющий TAG]
Edge Id           запись LOCAL Reference
документ          запись DOC-POINTER Reference (Issuer, ID документа, ID версии). Для списка версий Codec — CODEC-POINTER
хеш содержимого   16 WORD   (PUBLICATION)
категория причины 1 WORD    (TOMBSTONE)
ПолеШиринаОписание
Edge Idзапись LOCAL ReferenceПорядковый номер в списке. Нумеруется с 1 и дописывается подряд
документзапись DOC-POINTERОдна версия опубликованного документа (DOC-POINTER). Issuer и ID документа те же, что у документа, которому посвящён этот список. Благодаря этому документ списка сам говорит, чей это список, и без пути. ID версии — порядковый номер внутри документа (версия документа), 0 (последняя) не используется. Для списка версий Codec используется CODEC-POINTER (Issuer, Codec ID, ID версии)
хеш содержимого16 WORDХеш содержимого этой версии (SHA-256, хеш содержимого документа)
категория причины1 WORDКод категории причины удаления. Таблица кодов — открытая проблема
  • Длина после DOC-POINTER для каждого кода фиксирована (16, 0, 1 WORD). Если иначе, запись отклоняется.
  • Момент времени в запись не помещается. RECORDED-AT документа списка, в котором запись впервые появилась, — это момент публикации, deprecate или удаления.

Документ списка версий

Публикатор ведёт для каждого документа один документ списка версий, дописывая его: /<Issuer>/docs/<ID документа>/versions.geul (для Codec /<Issuer>/codecs/<Codec ID>/versions.geul, для списка Issuer см. ниже). В один список входят все версии этого документа, опубликованные этим публикатором.

DOC-1WORD/2WORD/4WORD     полная длина
  SPEC-VERSION            0x0001 (v1)
  PARENT                  Value SHA-256-DIGEST. Хеш содержимого предыдущего документа списка (у первого списка нет)
  RECORDED-AT             Value POSIX-TIMESTAMP-SECONDS. Момент выпуска этого списка
  NEXT-LOCAL-ID           LOCAL ID, назначаемый следующим (если есть версии)
  SIGNATURE               подпись публикатора. Подписывается хеш содержимого этого документа списка
BODY
  PUBLICATION · DEPRECATION · TOMBSTONE …
END
  • Meta HEAD: SPEC-VERSION, PARENT, RECORDED-AT, NEXT-LOCAL-ID, SIGNATURE.
  • В документе списка версий DOC-ID не размещается (исключение для документов списков, DOC-ID). Список — не опубликованный документ, а запись, прилагаемая к документу. Чей это список, говорит DOC-POINTER (ID документа) записи. Поэтому, даже если документ получен без пути (hashes/, дамп), известно, чей это список.
  • ID документа во всех записях должны принадлежать документу, которому посвящён этот список. Записи другого документа отклоняются.
  • В документе списка версий IMPORT не размещается, используются только Codec слоя 0. В BODY размещаются только PUBLICATION, DEPRECATION и TOMBSTONE. BIND имени документа не размещается (адрес публикации и список версий).
  • Новый документ списка ставит BODY предыдущего документа списка в начало без изменений и дописывает записи. Ничего не исправляется, не удаляется и не переставляется.
  • Список подписывает публикатор. Публикацию geul.org подписывает geul.org (Issuer GEUL), частную публикацию — её Issuer.
  • ID документа 0x0000000000000000 — документ индекса определений терминов Issuer (Issuer и публикация). Сам Issuer указывается через ISSUER-POINTER.

Список версий документа-списка

Документ-список — это один список Issuer issuers/ (адрес публикации и список версий). Список Issuer тоже начинается с версии 1 и имеет список версий issuers/versions.geul. Запись указывает на версию списка через DOC-POINTER зарезервированного ID документа (0x00000000, 0xFFFFFFFFFFFFFFFF, ID версии).

  • Формат записей тот же, что выше. Поэтому и при получении через hashes/ известно, чей это список.
  • Сам документ-список (<ID версии>.geul) тоже не содержит DOC-ID.
  • ID документа 0xFFFFFFFFFFFFFFFF ни у какого Issuer не принимается по адресу <Issuer>/docs/<ID документа>/ (404).
  • latest.geul списка — псевдоним, который не хранится. В этом списке версий находится самая новая версия, и выдаются её байты.

Правила

  • ID версии у PUBLICATION идёт по возрастанию с 1 без пропусков. ID версии назначает публикатор.
  • Один и тот же хеш содержимого повторно не публикуется. Если он уже есть, возвращается его ID версии.
  • DEPRECATION и TOMBSTONE указывают только на ID версии PUBLICATION, встречавшейся раньше. Указание на несуществующую версию отклоняется.
  • Состояние версии вычисляется последовательным применением записей. Опубликована → deprecated → удалена. Удалённая версия повторно не публикуется и не выдаётся.
  • Последняя версия — наибольший ID версии, который не deprecated и не удалён.
  • Когда ID версии доходит до конца 2 WORD, этот документ больше не публикуется, а выпускается под новым ID документа.

Адреса

/.well-known/geul/<Issuer>/docs/<ID документа>/versions.geul        последний документ списка (изменяемый)
/.well-known/geul/<Issuer>/codecs/<Codec ID>/versions.geul          последний документ списка Codec (изменяемый)
/.well-known/geul/issuers/versions.geul                            последний список версий списка Issuer (изменяемый)
/.well-known/geul/<Issuer>/hashes/<хеш содержимого>.geul            прошлый документ списка (неизменяемый)
  • Изменяемым является адрес последнего списка. Полученный список проверяется по подписи, RECORDED-AT и цепочке PARENT.
  • Все прошлые документы списков остаются в <Issuer>/hashes/. По цепочке PARENT можно восстановить список на любой момент.

Проверка

  • В документе списка должна быть SIGNATURE ключа публикатора, заданного для него.
  • ID документа записи должен совпадать с запрошенным ID документа.
  • Хеш содержимого предыдущего списка, сохранённый в записи блокировки, должен быть в цепочке PARENT нового списка. BODY того списка должен совпадать с начальной частью BODY нового списка.
  • Хеш содержимого полученного документа должен совпадать со значением, записанным в PUBLICATION этого ID версии, а DOC-ID документа — с запрошенными Issuer и ID документа. У документа списка DOC-ID нет.

Открытые проблемы

  • Таблица кодов категорий причин.
  • Алгоритм подписи по умолчанию и раскладка Payload SIGNATURE.
  • Момент и формат перехода к журналу Merkle (доказательства включения и согласованности), когда список вырастет.
  • Защита от отката на уровне Issuer. Поскольку список для каждого документа образует отдельную цепочку, атака, при которой подсовывается старый список лишь одного документа, блокируется только цепочкой этого документа.

Связанные страницы

Исходный текст документа спецификации

Документ спецификации 0x00000000/codecs/0x00000B90/latest.geul, прочитанный через geul show (16-ричные цифры в верхнем регистре).

SPEC-VERSION 0x0001
DOC-ID 0x04260000000000000B9000000000
BODY
#1 DECLARE 0x0B90
#2 FIELD #1 record
#6 CODEC #2 0x0410
#4 BIND #1 "DEPRECATION"
#5 BIND #2 "doc"
#7 CODEC #2 0x0420