تشير GEUL إلى المستند بمعرّفات (Issuer ومعرّف المستند ومعرّف الإصدار) لا بنص URL. ويتحدد العنوان من المعرّفات. تحدد هذه الصفحة قواعد النشر اللازمة لتعمل الـ encoder والـ decoder والمفسِّر معاً متشابكة. أما درجات Issuer وطريقة الإتاحة فيحددها Issuer والنشر.
كتابة المعرّف
تُكتب المعرّفات المستخدمة في العنوان بـ hex.
- البادئة
0xبأحرف صغيرة. ويُكتب hex بأحرف كبيرة A-F. ويحوّل المفسِّر العنوان المكتوب بأحرف صغيرة إلى كبيرة عند البحث. - عدد الخانات ثابت يساوي العرض × 4. ولا تُحذف الأصفار في المقدمة، فعدد الخانات هو العرض.
- عند كتابة العنوان يُكتب Issuer بعدد خانات عرض منحه: 8 خانات لـ 2 WORD، و16 لـ 4 WORD، و64 لـ 16 WORD.
- عند القراءة يقبل المفسِّر Issuer بـ 8 خانات و16 و64 جميعاً. وتُعامل الصيغة الأطول بإضافة أصفار في المقدمة إلى معرّف Issuer القصير على أنها Issuer نفسه (
0x00000001و0x0000000000000001هما Issuer واحد، Issuer والنشر).
| الهدف | العرض | عدد الخانات | مثال |
|---|---|---|---|
| Issuer | 2 WORD | 8 | 0x00000001 |
| Issuer | 4 WORD | 16 | 0x0000000100000000 |
| Issuer | 16 WORD | 64 | 0x + 64 خانة |
| معرّف Codec | 2 WORD | 8 | 0x00000AA0 |
| معرّف المستند | 4 WORD | 16 | 0x0000000000000000 |
| معرّف الإصدار | 2 WORD | 8 | 0x00000003 |
| تجزئة المحتوى | 16 WORD | 64 | 0x + 64 خانة |
- معرّف Codec للرمز المباشر في GEUL هو TAG WORD الخاصة به (L=0) مكتوبةً في 32 بتاً (TRIPLE
0x0AAL←0x00000AA0). ولا يتداخل لأن Kind داخل TAG. - يوضع Codec بصيغة ISSUER الخاصة بـ Issuer آخر تحت
codecs/في ذلك Issuer برقم Codec الخاص بالسجل. مثال: IETF CRC32C في0x00000007/codecs/0x0000C000/. - معرّف Codec لـ Codec الخاص بـ Issuer هو رقم Codec في السجل (2 WORD). ويخصص Issuer أرقام Codec بحيث لا تتداخل داخل
<Issuer>/codecs/الخاص به بصرف النظر عن Kind (Reference وValue وEdge). ولا ينقسم العنوان بحسب Kind (لا مجلدات مثلreferences/وvalues/وedges/). - يعدّ المفسِّر خطأً أن يختلف Kind السجل عن Kind هدف DECLARE في مستند Codec الخاص به.
- يرفض النشر رفع Codec آخر على معرّف Codec نفسه.
- قواعد معرّف الإصدار (من 1، و
0هو الأحدث، تخصصه جهة النشر، وعند الاستنفاد يُستخدم معرّف مستند جديد) يحددها المستند.
عنوان النشر
/.well-known/geul/issuers/latest.geul أحدث قائمة Issuer
/.well-known/geul/issuers/<معرّف الإصدار>.geul قائمة Issuer بإصدار محدد
/.well-known/geul/issuers/versions.geul قائمة إصدارات قائمة Issuer
/.well-known/geul/<Issuer>/codecs/<معرّف Codec>/latest.geul أحدث Codec
/.well-known/geul/<Issuer>/codecs/<معرّف Codec>/<معرّف الإصدار>.geul Codec بإصدار محدد
/.well-known/geul/<Issuer>/codecs/<معرّف Codec>/versions.geul قائمة إصدارات Codec
/.well-known/geul/<Issuer>/docs/<معرّف المستند>/latest.geul أحدث مستند
/.well-known/geul/<Issuer>/docs/<معرّف المستند>/<معرّف الإصدار>.geul مستند بإصدار محدد
/.well-known/geul/<Issuer>/docs/<معرّف المستند>/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>/وdocs/<معرّف المستند>/وhashes/. وقائمة Issuer أيضاً من الإصدار 1 وفيهاversions.geul(مستند القوائم). latest.geulاسم محجوز واسم مستعار. ولا يُخزَّن. بل يُبحث فيversions.geulفي الموضع نفسه عن أحدث إصدار فتُعاد بايتات ذلك الإصدار كما هي. ولا يُعاد التوجيه. وكلlatest.geulفي قائمة Issuer وCodec والمستند متماثلة.- العنوان المرجعي لإصدار واحد هو
/<Issuer>/docs/<معرّف المستند>/<معرّف الإصدار>.geul. وفي Codec هو/<Issuer>/codecs/<معرّف Codec>/<معرّف الإصدار>.geul. والعناوين الأخرى التي تعطي المحتوى نفسه تشير إلى العنوان المرجعي بـLink: rel=canonical. - عنوان الإصدار المحدد وعنوان تجزئة المحتوى ثابتان لا يتغيران. ويمكن وضع العنوان الثابت في ذاكرة تخزين مؤقت دائمة وفي CDN. ويتحقق المتلقي بتجزئة المحتوى في قائمة الإصدارات (أو سجل القفل).
- للبحث بتجزئة المحتوى يجب معرفة Issuer. ولا يوجد بحث عالمي بالتجزئة وحدها.
- مستند Codec لا معرّف مستند له. ويشير إلى نفسه وإصداره بـ CODEC-POINTER (Issuer ومعرّف Codec ومعرّف الإصدار).
- يبدأ المعرّف دائماً بـ
0x. ولهذا لا تتداخل الأسماء المحجوزة (issuersوcodecsوdocsوhashesوlatest.geulوversions.geul) أو الأسماء التي يضعها الناس مع المعرّف حتى لو كانت كلمات hex فقط مثلaddوcafe. - لا يوضع الموضع (من أي خادم يُجلب) في محتوى المستند. فلو وُضع لتغيرت تجزئة المحتوى عند تغير العنوان. والموضع تحدده إعدادات الجهة التي تتلقى المستند.
صيغة النشر والبحث
- العنوان عنوان منطقي. وتستطيع جهة النشر أن تنشر ملفات منفردة أو pack، وإن كان pack فلا يمكن جلبه مباشرة من عنوان URL بل يُقرأ بمفسِّر GEUL.
- يُبحث عنه بالعنوان نفسه سواء خُزِّن ملفاً منفرداً أم pack أم zstd pack. والعنوان الخارج عن الصيغ العشر أعلاه والعنوان غير الموجود هو 404 (غير موجود).
أداة سطر الأوامر geul (gogeul):
geul get <العنوان> يُخرج المستند GEUL الخام الثنائي إلى المخرج القياسي
geul show <العنوان> يعرض المستند نصاً
- يقبل
geul getعناوينfile://وhttps://. والعنوان الخارج عن الصيغ العشر والعنوان غير الموجود ينتهيان بـ 404 (غير موجود).
تضع pkg/resolve في مكتبة Go المسماة gogeul دالة بحث لكل عنوان. وكلها تعيد ثنائي GEUL الخام ([]byte). ومعرّف الإصدار يبدأ من 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) // غير الصيغ العشر هو 404 (غير موجود)
Fetch(ctx, Addr) ([]byte, error) // geul get = ParseAddr ← Fetch ← المخرج القياسي
تحديد الصيغة
- ينتهي عنوان النشر بـ
.geulوهو ثنائي (application/vnd.geul). - النسخة الثنائية هي الأصل المعتمد للمستند. وتُحسب تجزئة المحتوى والتوقيع من النسخة الثنائية فقط.
مستند القوائم
مستند القوائم هو قائمة Issuer issuers/ وحدها. وتربط Issuer بالنطاق (قائمة Issuer). وهي من الإصدار 1 وفيها versions.geul. ومعرّف مستند القائمة هو معرّف المستند المحجوز 0xFFFFFFFFFFFFFFFF (Issuer geul.org 0x00000000). وتحجز كل Issuer معرّفَي المستند 0x0000000000000000 و0xFFFFFFFFFFFFFFFF (Issuer والنشر).
latest.geulاسم مستعار لا يُخزَّن. يُبحث فيversions.geulعن أحدث إصدار وتُخرج بايتاته.- يشير PUBLICATION وDEPRECATION وTOMBSTONE في
issuers/versions.geulإلى إصدار القائمة بـ DOC-POINTER (0x00000000و0xFFFFFFFFFFFFFFFFومعرّف الإصدار). ولهذا يُعرف حتى عند الجلب بـhashes/ما الذي تمثله القائمة (PUBLICATION). - معرّف المستند
0xFFFFFFFFFFFFFFFFلا يُجلب في أي Issuer بعنوان<Issuer>/docs/<معرّف المستند>/(404). أما معرّف المستند المحجوز الآخر0x0000000000000000فهو مستند فهرس تعريفات المصطلحات في ذلك Issuer ويوضع تحتdocs/(Issuer والنشر). - لا يوضع
DOC-IDفي مستند القوائم. فيحدد DOC-POINTER في السجل المستندَ الذي تخصه القائمة (DOC-ID). - المستندات وCodec تُبحث مباشرة بالمعرّف المحسوب من السجل دون قائمة (اسم المستند).
اسم النطاق
اسم النطاق ليس عنوان URL للنشر. والعنوان الذي كُتب فيه النطاق في موضع <Issuer> أو كُتب فيه اسم في موضع المعرّف هو خارج الصيغ العشر أعلاه فهو 404 (غير موجود). ولا يوجد إعادة توجيه من الاسم إلى عنوان المعرّف أيضاً.
- اسم النطاق مدخل للمفسِّر وCLI. ويحوّل المفسِّر النطاق إلى معرّف Issuer بـ BIND في قائمة Issuer
issuers/. ويُترك المعرّف المحوَّل في سجل القفل. ولا يوجد عنوان باسم المستند (اسم المستند). - العنوان المرجعي ومفتاح الذاكرة المؤقتة والهدف الموقَّع هو عنوان المعرّف.
- يُكتب النطاق بأحرف صغيرة، ويُكتب النطاق الدولي بصيغة IDNA (punycode). ولا تُلحق
.في النهاية. - Issuer من 16 WORD الذي لا جهة تسجيل له والبيئات المعزولة التي لا تصل إلى geul.org لا تستطيع استخدام اسم النطاق. فتستخدم المعرّف.
قائمة 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 (Issuer الخاص بـ GEUL)، وإذا تغيرت أُلحق ولا يُصحَّح (قاعدة السلسلة نفسها كما في قائمة الإصدارات).
اسم المستند
لا يوجد عنوان باسم المستند. المستندات وCodec تُبحث بالمعرّف.
- لا يوجد فهرس يحوّل اسم المستند أو اسم Codec إلى معرّف. ولا يوضع BIND لاسم المستند في قائمة الإصدارات (PUBLICATION).
- الفهرس الذي يتصفحه الناس تنشئه الأداة (العارض) من جرد pack.
- العنوان المرجعي ومفتاح الذاكرة المؤقتة والهدف الموقَّع هو عنوان المعرّف. وIMPORT والاستشهادات داخل المستند بالمعرّف وحده.
- العنوان المقروء للبشر (بحسب اللغة) يُلحق بـ LABEL العبارة.
المستند المحذوف
- عنوان الإصدار الذي أُلغي بحذف قانوني أو بحكم الوظيفة (TOMBSTONE) هو أيضاً 404 (غير موجود) كغيره من العناوين غير الموجودة.
- الإصدار الذي وُصي بوقف استخدامه (DEPRECATION) ليس 404. بل يُعطى بعنوان ذلك الإصدار كالمعتاد.
- يبقى الحذف في قائمة الإصدارات سجلَّ TOMBSTONE (DOC-POINTER لذلك الإصدار وفئة السبب).
الطبقات
تعبّر GEUL عن المصدر والـ Meta والقوائم بمستندات GEUL. والحد الأدنى اللازم لقراءتها مضمَّن في الـ decoder لقطع الدوران. وكل طبقة تعتمد على التي تحتها فقط.
| الطبقة | المحتوى | تعتمد على |
|---|---|---|
| الطبقة 0 | قواعد مضمَّنة في الـ decoder: التأطير، وتجزئة المحتوى، والتحقق من التوقيع، وCodec سجلات قائمة الإصدارات (PUBLICATION وDEPRECATION وTOMBSTONE)، ومفردات مواصفة Codec (DECLARE وFIELD وENUM وCODEC)، وعلامة الموضع (0x0000 و0x0010 و0x0020)، ومفاتيح الثقة التي تُستلم من خارج المستند | لا شيء. ولا تُجلب |
| الطبقة 1 | مستند قائمة الإصدارات | الطبقة 0 |
| الطبقة 2 | المستندات العامة، والـ codebook، ومستندات مواصفة Codec، ومستند مفاتيح تحقق Issuer | تُبحث بالطبقة 1 وتُتحقق بالطبقة 0 |
- لا تعتمد أي طبقة على طبقتها أو على ما فوقها.
- يُميَّز بين ما يُعبَّر عنه بـ GEUL وما لا يُقرأ إلا بتفسيره بـ GEUL. فالطبقة 0 يمكن التعبير عنها بـ GEUL لكن تفسيرها لا يحتاج إلى بحث.
- النواة الثابتة التي لا يمكن تحويلها إلى مستند TOULMIN، كمعنى الحكم، توضع هنا أيضاً (TOULMIN).
قائمة الإصدارات
تكتب جهة النشر لكل مستند مستند قائمة إصدارات واحداً تُلحق به (/<Issuer>/docs/<معرّف المستند>/versions.geul، وفي Codec /<Issuer>/codecs/<معرّف Codec>/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 | يحذف الإصدار المنشور (حذف قانوني أو بحكم الوظيفة). ويكتب فئة السبب |
- السجلات للإلحاق فقط. فلا تُصحَّح ولا تُحذف ولا يُغيَّر ترتيبها. والـ deprecate والحذف أيضاً يُلحقان سجلاً. وتضع القائمة الجديدة BODY القائمة السابقة كما هو في المقدمة وتُلحق السجلات، وتتصل القوائم بسلسلة تجزئات
PARENT. - المقصود ألا يُصحَّح سجل النشر، وهذا يختلف عن تنقيح محتوى المستند (المستند). وتُحسب الحالة الحالية للإصدار بتطبيق السجلات تباعاً.
- معرّف الإصدار تصاعدي من 1 بلا ثغرات. ولا يُعاد نشر المحتوى نفسه.
- الإصدار الأحدث هو أعلى إصدار لم يُوصَ بإيقافه ولم يُحذف.
- لا يوضع وقت في السجل. ووقت النشر هو
RECORDED-ATفي أول قائمة ورد فيها ذلك السجل. - لا يوضع
DOC-IDفي قائمة الإصدارات. فيحدد DOC-POINTER في السجل المستندَ الذي تخصه القائمة (معرّف المستند، وفي قائمة Issuer معرّف المستند المحجوز). - لا تضع قائمة الإصدارات IMPORT ولا تستخدم إلا Codec الطبقة 0. ولا يوضع في BODY إلا PUBLICATION وDEPRECATION وTOMBSTONE.
- قوائم الإصدارات السابقة يُشار إليها بتجزئة المحتوى وحدها (
<Issuer>/hashes/<تجزئة المحتوى>.geul)، ويُوصَل التاريخ بسلسلةPARENT. - العناوين المتغيرة هي
latest.geulوversions.geul. ولأن المؤشر المتغير لا يمكن جعله مستنداً، يُتحقق منه بتوقيع القائمة المستلمة وRECORDED-ATوPARENT.
جهة التوقيع
| التوقيع | الجهة | الهدف |
|---|---|---|
| توقيع المستند | Issuer ذلك المستند | تجزئة محتوى المستند (Issuer والنشر) |
| توقيع القائمة | جهة النشر التي خصصت معرّف الإصدار | تجزئة محتوى قائمة الإصدارات |
- النشر في geul.org يخصص فيه geul.org (Issuer الخاص بـ GEUL) معرّف الإصدار ويوقّع القائمة، وفي النشر الخاص يفعل ذلك Issuer نفسه.
- المؤلف مسؤول عن المحتوى، وجهة النشر مسؤولة عن الأرقام والترتيب.
التحقق
- يُستبعد التوقيع من تجزئة المحتوى فلا تتغير التجزئة إن حُذف. ولهذا يكون التحقق “يجب أن يوجد توقيع بمفتاح محدد” لا “يُتحقق منه إن وُجد”. والمفتاح المطلوب تحدده إعدادات الثقة في المفسِّر وسجل القفل.
- يترك المفسِّر في سجل القفل تجزئة محتوى آخر قائمة رآها. وإذا لم تكن تلك التجزئة في سلسلة
PARENTللقائمة المستلمة حديثاً رفضها (منع الرجوع إلى الوراء والتفرع). - تنسخ المرايا والبيئات المعزولة سلسلة قوائم الإصدارات معاً. ويكفي المفتاح العام للتحقق دون اتصال.
- المستند المستلم يُتحقق منه بتجزئة المحتوى أياً كان مصدره. فلا حاجة للوثوق بالمصدر.
حل التبعيات
- يكتب المستند المستندات التي يعتمد عليها بـ IMPORT-DOC في HEAD.
- لا يَعِد الإصدار الجديد بالتوافق مع الإصدار السابق. ولهذا لا يُوحَّد إصدار مستند واحد في الرسم البياني كله (لا يُستخدم اختيار الحد الأدنى للإصدار).
- كل
IMPORT-DOCمرتبط بالنسخة التي ثبّتها. ويمكن أن توجد عدة نسخ من المستند نفسه معاً في رسم بياني واحد (حكم يستشهد بالقانون القديم وحكم يستشهد بالقانون النافذ). وتُحل المراجع بـ (المستند، الإصدار، LOCAL ID). - الاستيراد بالأحدث (الإصدار
0) مرتبط بأحدث نسخة وقت التفسير. وإذا فُسِّر في زمن محدد ارتبط بالنسخة النافذة في ذلك الزمن (المستند). - الاستيراد المثبَّت بمعرّف الإصدار قابل لإعادة الإنتاج (محتوى معرّف الإصدار ثابت ويُتحقق منه بسجل القفل).
نوع الوسائط
- نوع الوسائط لمستند GEUL هو
application/vnd.geul. والامتداد.geul. - وحتى لو نُقل إلى الشجرة القياسية
application/geulيظلapplication/vnd.geulمقبولاً.
مسائل مفتوحة
- معالجة تفرع معرّفات الإصدار (معرّف الإصدار نفسه بمحتوى مختلف) في النشر الخاص وIssuer من 16 WORD والبيئات المعزولة.
- بنية HEAD لقائمة Issuer
issuers/وصيغة التوقيع والسلسلة. وقاعدة التسمية لـ Issuer بلا نطاق (4 WORD)، ومعالجة نزاعات الأسماء وحدّ الطول. - وقت الانتقال وصيغته من السلسلة كاملة إلى سجل Merkle (إثبات التضمين والاتساق) حين تكبر القائمة.
- Meta الذي يكتب في HEAD الـ Issuer الذي يوفر الموضع.