GEUL указывает на документ не строкой URL, а ID (Issuer, ID документа, ID версии). Адрес определяется по ID. Эта страница задаёт правила публикации, необходимые для согласованной работы кодировщиков, декодеров и интерпретаторов. Классы Issuer и способы раскрытия определяет Issuer и публикация.
Запись ID
ID, используемые в адресе, записываются в hex.
- Префикс — строчный
0x. Шестнадцатеричные цифры пишутся заглавными A-F. Интерпретатор приводит адрес, записанный строчными, к заглавным при поиске. - Число цифр фиксировано: ширина × 4. Ведущие нули не опускаются, число цифр и есть ширина.
- При записи адреса Issuer пишется с числом цифр, соответствующим ширине выдачи: 2 WORD — 8 цифр, 4 WORD — 16 цифр, 16 WORD — 64 цифры.
- При чтении Issuer принимается в любой из форм: 8, 16 и 64 цифры. Длинная запись короткого ID Issuer с ведущими нулями ищется как тот же Issuer (
0x00000001и0x0000000000000001— один Issuer, Issuer и публикация).
| Объект | Ширина | Число цифр | Пример |
|---|---|---|---|
| Issuer | 2 WORD | 8 | 0x00000001 |
| Issuer | 4 WORD | 16 | 0x0000000100000000 |
| Issuer | 16 WORD | 64 | 0x + 64 цифры |
| Codec ID | 2 WORD | 8 | 0x00000AA0 |
| ID документа | 4 WORD | 16 | 0x0000000000000000 |
| ID версии | 2 WORD | 8 | 0x00000003 |
| Хеш содержимого | 16 WORD | 64 | 0x + 64 цифры |
- Codec ID прямого кода GEUL — это его TAG WORD (L=0), записанный как 32-битное значение (TRIPLE
0x0AAL→0x00000AA0). Kind содержится в TAG, поэтому пересечений нет. - Codec формата ISSUER другого Issuer помещается под
codecs/этого Issuer по номеру Codec из записи. Пример: IETF CRC32C —0x00000007/codecs/0x0000C000/. - Codec ID Codec Issuer — это номер Codec из записи (2 WORD). Issuer назначает номера Codec внутри своего
<Issuer>/codecs/без пересечений независимо от Kind (Reference, Value, Edge). Адрес по Kind не делится (папок вродеreferences/,values/,edges/нет). - Если Kind записи отличается от Kind цели DECLARE в документе этого Codec, интерпретатор считает это ошибкой.
- Публикация отвергает размещение другого Codec под тем же Codec ID.
- Правила ID версии (с 1,
0— последняя, назначает публикующая сторона, при исчерпании — новый ID документа) задаёт Документ.
Адрес публикации
/.well-known/geul/issuers/latest.geul Список Issuer, последний
/.well-known/geul/issuers/<ID версии>.geul Список Issuer, указанная версия
/.well-known/geul/issuers/versions.geul Список версий списка Issuer
/.well-known/geul/<Issuer>/codecs/<Codec ID>/latest.geul Codec, последний
/.well-known/geul/<Issuer>/codecs/<Codec ID>/<ID версии>.geul Codec, указанная версия
/.well-known/geul/<Issuer>/codecs/<Codec ID>/versions.geul Список версий Codec
/.well-known/geul/<Issuer>/docs/<ID документа>/latest.geul Документ, последний
/.well-known/geul/<Issuer>/docs/<ID документа>/<ID версии>.geul Документ, указанная версия
/.well-known/geul/<Issuer>/docs/<ID документа>/versions.geul Список версий документа
/.well-known/geul/<Issuer>/hashes/<хеш содержимого>.geul Поиск по хешу содержимого
Пример: /.well-known/geul/0x00000002/docs/0x0000000000000000/latest.geul
- Путь следует
.well-knownиз RFC 8615. geul.org и частная публикация используют один путь, различается только домен. Регистрируемый суффикс один —geul. - Список Issuer — это
issuers/. Codec, обычные документы и хеши разделяются под папкой Issuer наcodecs/<Codec ID>/,docs/<ID документа>/,hashes/. Список Issuer тоже начинается с версии 1 и имеетversions.geul(Документ-список). latest.geul— зарезервированное слово и псевдоним. Он не хранится. Изversions.geulна том же месте находится самая последняя версия, и байты этой версии отдаются как есть. Перенаправления нет. Всеlatest.geulсписка Issuer, Codec и документов устроены одинаково.- Канонический адрес одной версии —
/<Issuer>/docs/<ID документа>/<ID версии>.geul. У Codec —/<Issuer>/codecs/<Codec ID>/<ID версии>.geul. Другие адреса, отдающие то же содержимое, указывают на канонический адрес черезLink: rel=canonical. - Адрес с указанной версией и адрес по хешу содержимого неизменны. Неизменные адреса можно помещать в постоянный кэш и CDN. Получатель проверяет их по хешу содержимого из списка версий (или записи блокировки).
- Чтобы искать по хешу содержимого, нужно знать Issuer. Глобального поиска только по хешу нет.
- У документа Codec нет ID документа. Он указывает на себя и свою версию через CODEC-POINTER (Issuer, Codec ID, ID версии).
- ID всегда начинается с
0x. Поэтому зарезервированные имена (issuers,codecs,docs,hashes,latest.geul,versions.geul) и имена, данные человеком, не пересекаются с ID, даже если это слово из одних hex-цифр, напримерadd,cafe. - Местоположение (с какого сервера получать) в содержимое документа не помещается. Иначе при смене адреса менялся бы хеш содержимого. Местоположение определяет настройка принимающей стороны.
Форма публикации и поиск
- Адрес — логический. Публикующая сторона может выдавать отдельные файлы или pack, и если это pack, получить его напрямую по URL-адресу нельзя, он читается интерпретатором GEUL.
- Независимо от того, хранится ли он как отдельные файлы, pack или zstd pack, он находится по тому же адресу. Адрес вне перечисленных выше 10 форм и несуществующий адрес дают 404 (нет).
Инструмент командной строки geul (gogeul):
geul get <адрес> выводит чистый бинарный документ GEUL в стандартный вывод
geul show <адрес> показывает документ в виде текста
geul getпринимает адресаfile://иhttps://. Адрес вне 10 форм и несуществующий адрес завершаются 404 (нет).
pkg/resolve библиотеки Go gogeul содержит функцию поиска для каждого адреса. Все они возвращают чистый бинарный GEUL ([]byte). ID версии начинается с 1, поэтому Latest (0) — последняя. Несуществующий адрес — ошибка «нет» (ErrNotFound).
const Latest uint32 = 0
Issuers(ctx, v) / IssuersVersions(ctx)
Codec(ctx, issuer, codec, v) / CodecVersions(ctx, issuer, codec)
Doc(ctx, issuer, doc, v) / DocVersions(ctx, issuer, doc)
Hash(ctx, issuer, hash)
ParseAddr(s string) (Addr, error) // формы вне 10 — 404 (нет)
Fetch(ctx, Addr) ([]byte, error) // geul get = ParseAddr → Fetch → стандартный вывод
Указание формата
- Адрес публикации оканчивается на
.geulи является бинарным (application/vnd.geul). - Каноническая форма документа — бинарная. Хеш содержимого и подпись вычисляются только по бинарной форме.
Документ-список
Документ-список — один: список Issuer issuers/. Он связывает Issuer и домен (Список Issuer). Он начинается с версии 1 и имеет versions.geul. ID документа этого списка — зарезервированный ID документа 0xFFFFFFFFFFFFFFFF (Issuer geul.org 0x00000000). Каждый Issuer резервирует ID документа 0x0000000000000000 и 0xFFFFFFFFFFFFFFFF (Issuer и публикация).
latest.geul— несохраняемый псевдоним. Изversions.geulнаходится самая последняя версия, и отдаются её байты.- PUBLICATION, DEPRECATION и TOMBSTONE в
issuers/versions.geulуказывают на версию списка через DOC-POINTER (0x00000000,0xFFFFFFFFFFFFFFFF, ID версии). Поэтому даже при получении черезhashes/известно, чей это список (PUBLICATION). - ID документа
0xFFFFFFFFFFFFFFFFни у какого Issuer не отдаётся по адресу<Issuer>/docs/<ID документа>/(404). Другой зарезервированный ID документа,0x0000000000000000, — индексный документ определений терминов этого Issuer, и он помещается подdocs/(Issuer и публикация). - В документ-список
DOC-IDне ставится. Чей это список, сообщает DOC-POINTER в записи (DOC-ID). - Документы и Codec находятся без списка, сразу по ID, вычисленному из записи (Имя документа).
Доменное имя
Доменное имя — не URL-адрес публикации. Адрес, где на месте <Issuer> стоит домен или на месте ID стоит имя, находится вне 10 форм выше и даёт 404 (нет). Перенаправления с имени на адрес по ID тоже нет.
- Доменное имя — ввод для интерпретатора и CLI. Интерпретатор превращает домен в ID Issuer через BIND в списке Issuer
issuers/. Полученный ID остаётся в записи блокировки. Адреса по имени документа нет (Имя документа). - Канонический адрес, ключ кэша и объект подписи — адреса по ID.
- Домен пишется строчными, интернационализированный домен — в форме IDNA (punycode). Завершающая
.не ставится. - 16-WORD Issuer без реестра и изолированная от сети среда, не достигающая geul.org, доменные имена использовать не могут. Используется ID.
Список Issuer
Список Issuer — документ под /.well-known/geul/issuers/ (последний — issuers/latest.geul). Он связывает Issuer и его имя (домен).
BODY
BIND Subject = ISSUER-POINTER(Issuer) имя = "geul.org"
…
- Subject — ISSUER-POINTER (сам Issuer), а имя связывается через BIND.
- Имя — домен, прошедший подтверждение владения. Оно строчное, а интернационализированный домен пишется в IDNA (punycode). Одно имя связывается только с одним Issuer.
- Отображаемое человеком имя Issuer (по языкам) присоединяется к тому же Subject описанием LABEL.
- Подписывает geul.org (GEUL Issuer), при изменении дополняется и не исправляется (то же правило цепочки, что у списка версий).
Имя документа
Адреса по имени документа нет. Документы и Codec находятся по ID.
- Индекса, превращающего имя документа или имя Codec в ID, нет. Имя документа через BIND в списке версий тоже не ставится (PUBLICATION).
- Индекс для просмотра человеком строит инструмент (просмотрщик) по инвентарю pack.
- Канонический адрес, ключ кэша и объект подписи — адреса по ID. IMPORT и цитаты внутри документа делаются только по ID.
- Читаемый человеком заголовок (по языкам) присоединяется описанием LABEL.
Удалённые документы
- Адрес версии, отозванной удалением по закону или по должностному решению (TOMBSTONE), тоже даёт 404 (нет), как и другие несуществующие адреса.
- Версия, для которой рекомендован отказ от использования (DEPRECATION), не даёт 404. Она продолжает отдаваться по адресу этой версии.
- Удаление остаётся в списке версий записью TOMBSTONE (DOC-POINTER этой версии, категория причины).
Уровни
GEUL выражает в виде документов GEUL и происхождение, и Meta, и списки. Минимум, необходимый для их чтения, встроен в декодер, что разрывает цикл. Каждый уровень опирается только на нижние.
| Уровень | Содержание | На что опирается |
|---|---|---|
| Уровень 0 | Встроенные в декодер правила: фрейминг, хеш содержимого, проверка подписи, Codec записей списка версий (PUBLICATION, DEPRECATION, TOMBSTONE), словарь спецификации Codec (DECLARE, FIELD, ENUM, CODEC), маркер места (0x0000, 0x0010, 0x0020), доверенные ключи, получаемые вне документа | Ни на что. Поиска не выполняет |
| Уровень 1 | Документ списка версий | Уровень 0 |
| Уровень 2 | Обычные документы, кодекбуки, документы спецификации Codec, документ ключей проверки Issuer | Находятся через уровень 1, проверяются через уровень 0 |
- Ни один уровень не опирается на себя или на вышестоящие.
- Следует различать то, что выражается на GEUL, и то, что читается только интерпретацией средствами GEUL. Уровень 0 можно выразить на GEUL, но для его интерпретации поиск не требуется.
- Фиксированное ядро, которое нельзя превратить в документ TOULMIN, как смысл вердикта, тоже помещается здесь (TOULMIN).
Список версий
Публикующая сторона для каждого документа ведёт один документ списка версий (/<Issuer>/docs/<ID документа>/versions.geul, для Codec — /<Issuer>/codecs/<Codec ID>/versions.geul, для списка Issuer — issuers/versions.geul). Формат записей и структуру документа задаёт PUBLICATION.
DOC-*
SPEC-VERSION
PARENT хеш содержимого предыдущего списка версий
RECORDED-AT время выпуска этого списка
NEXT-LOCAL-ID LOCAL ID, назначаемый следующим
SIGNATURE подпись публикующей стороны
BODY
PUBLICATION #1 документ@1 хеш содержимого
PUBLICATION #2 документ@2 хеш содержимого
DEPRECATION #3 документ@1
…
END
| Edge | Значение |
|---|---|
| PUBLICATION | Публикует одну версию документа и её хеш содержимого |
| DEPRECATION | Помечает опубликованную версию рекомендацией отказа от использования. Продолжает интерпретироваться |
| TOMBSTONE | Удаляет опубликованную версию (по закону или по должностному решению). Записывается категория причины |
- Записи только добавляются. Их не исправляют, не удаляют и не переставляют. Устаревание и удаление тоже добавляются записями. Новый список ставит BODY предыдущего списка как есть в начало и добавляет записи, а списки связываются цепочкой хешей
PARENT. - Это лишь означает, что запись о публикации не исправляется, и не то же самое, что редакция содержимого документа (Документ). Текущее состояние версии вычисляется последовательным применением записей.
- ID версии идёт с 1 по возрастанию без пропусков. Одно и то же содержимое повторно не публикуется.
- Последняя версия — самая высокая версия, для которой нет ни рекомендации об отказе, ни удаления.
- Время в записи не ставится. Временем публикации является
RECORDED-ATсписка, в котором эта запись впервые появилась. - В список версий
DOC-IDне ставится. Чей это список, сообщает DOC-POINTER в записи (ID документа, для списка Issuer — зарезервированный ID документа). - Список версий не содержит IMPORT и использует только Codec уровня 0. В BODY ставятся только PUBLICATION, DEPRECATION и TOMBSTONE.
- На прошлые списки версий указывают только по хешу содержимого (
<Issuer>/hashes/<хеш содержимого>.geul), а история связывается цепочкойPARENT. - Изменяемые адреса —
latest.geulиversions.geul. Изменяемый указатель нельзя сделать документом, поэтому он проверяется по подписи полученного списка,RECORDED-ATиPARENT.
Субъект подписи
| Подпись | Субъект | Объект |
|---|---|---|
| Подпись документа | Issuer этого документа | Хеш содержимого документа (Issuer и публикация) |
| Подпись списка | Публикующая сторона, назначившая ID версии | Хеш содержимого списка версий |
- Публикацию на geul.org выполняет geul.org (GEUL Issuer), частную — сам этот Issuer: он назначает ID версий и подписывает список.
- Автор отвечает за содержимое, публикующая сторона — за номера и порядок.
Проверка
- Подпись исключается из хеша содержимого, поэтому при её удалении хеш не меняется. Поэтому проверка выполняется не как «если подпись есть, проверить», а как «подпись заданного ключа должна быть». Требуемый ключ определяют настройки доверия интерпретатора и запись блокировки.
- Интерпретатор сохраняет в записи блокировки хеш содержимого последнего виденного списка. Если этого хеша нет в цепочке
PARENTвновь полученного списка, список отвергается (защита от отката и ветвления). - Зеркала и изолированные среды копируют цепочку списков версий вместе. Если есть открытый ключ, проверка выполняется офлайн.
- Полученный документ проверяется по хешу содержимого, откуда бы он ни пришёл. Доверять источнику не требуется.
Разрешение зависимостей
- Документ записывает зависимые документы через IMPORT-DOC в HEAD.
- Новая версия не обещает совместимости с предыдущей. Поэтому версии одного документа во всём графе в одну не сводятся (минимальный выбор версий не применяется).
- Каждый
IMPORT-DOCпривязан к зафиксированной им редакции. В одном графе могут одновременно находиться несколько редакций одного документа (решение, цитирующее прежний закон, и решение, цитирующее действующий закон). Ссылка разрешается как (документ, версия, LOCAL ID). - Импорт последней (версия
0) привязан к последней редакции на момент интерпретации. Если интерпретация выполняется на заданный момент, он привязан к редакции, действовавшей в этот момент (Документ). - Импорт, зафиксированный по ID версии, воспроизводим (содержимое ID версии неизменно и проверяется по записи блокировки).
Медиатип
- Медиатип документа GEUL —
application/vnd.geul. Расширение —.geul. - Даже при переносе в стандартное дерево
application/geulпродолжает приниматьсяapplication/vnd.geul.
Открытые проблемы
- Обработка случая, когда ID версии расходятся (один ID версии, разное содержимое) при частной публикации, 16-WORD Issuer и изолированных средах.
- Состав HEAD списка Issuer
issuers/, формат подписи и цепочки. Правила имён для Issuer без домена (4 WORD), обработка споров об именах и предел длины. - Момент и формат перехода от полной цепочки к журналу Merkle (доказательства включения и согласованности), когда список вырастет.
- Meta, записывающий в HEAD Issuer, предоставляющий местоположение.