PUBLICATION, DEPRECATION и TOMBSTONE — Edge-высказывания, фиксирующие публикацию версии документа, рекомендацию прекратить её использование и удаление; эта страница задаёт также спецификацию документа списка версий, записываемого этими Edge (Codec 0x0B8L~0x0BAL).
| Пункт | Значение |
|---|---|
| Имя | DEPRECATION (BIND документа спецификации DEPRECATION) |
| TAG ID | 0x0B9L |
| Codec ID | 0x00000B90 |
| Документ спецификации | 0x00000000/codecs/0x00000B90/ (цель DECLARE 0B90) |
| Раздел | 5 0101 (Edge-высказывание), смещение C внутри раздела = 25 |
| Kind | Edge · семейство: высказывание, группа: прочее |
| TAG WORD | 0000 1011 1001 LLLL (000K KKKC CCCC LLLL) |
| Описание в индексе | Deprecate опубликованной версии. DOC-POINTER |
| Сторона Hugo | edge/publication.md (эта страница рассматривает также PUBLICATION и TOMBSTONE) |
Поля (документ спецификации)
Порядок FIELD в документе — это порядок полей Payload (документ спецификации Codec). Edge Id у Edge не объявляется через FIELD.
| Порядок | Поле (BIND) | FIELD | Ширина | Принимаемый формат (CODEC) | ENUM |
|---|---|---|---|---|---|
| 1 | doc | #2 | запись | 0410 DOC-POINTER, 0420 CODEC-POINTER |
Это Edge-высказывания, фиксирующие публикацию, deprecate и удаление документа, и спецификация документа списка версий, записываемого этими Edge. Они задают формат списка версий из раздела адрес публикации и список версий.
Коды
| Codec | Имя | Payload |
|---|---|---|
0x0B8L | PUBLICATION | Edge Id, DOC-POINTER, хеш содержимого |
0x0B9L | DEPRECATION | Edge Id, DOC-POINTER |
0x0BAL | TOMBSTONE | Edge 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