تشير 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 والنشر).
الهدفالعرضعدد الخاناتمثال
Issuer2 WORD80x00000001
Issuer4 WORD160x0000000100000000
Issuer16 WORD640x + 64 خانة
معرّف Codec2 WORD80x00000AA0
معرّف المستند4 WORD160x0000000000000000
معرّف الإصدار2 WORD80x00000003
تجزئة المحتوى16 WORD640x + 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 الذي يوفر الموضع.