GEUL מצביעה על מסמך לא באמצעות מחרוזת URL אלא באמצעות ID (Issuer, מזהה מסמך, מזהה גרסה). הכתובת נקבעת מה-ID. דף זה קובע את כללי הפרסום הדרושים כדי שמקודדים, מפענחים ומפרשים יפעלו יחד. דרגות ה-Issuer ואופני החשיפה נקבעים ב-Issuer ופרסום.
ייצוג ID
ID המשמש בכתובת נכתב ב-hex.
- התחילית היא
0xבאותיות קטנות. ספרות hex נכתבות באותיות גדולות A-F. המפרש ממיר גם כתובת שנכתבה באותיות קטנות לגדולות לפני החיפוש. - מספר הספרות קבוע ברוחב × 4. אין להשמיט אפסים מובילים, ומספר הספרות הוא הרוחב עצמו.
- בכתיבת כתובת, Issuer נכתב במספר הספרות של רוחב ההנפקה שלו: 8 ספרות ל-2 WORD, 16 ל-4 WORD, 64 ל-16 WORD.
- בקריאה מתקבלים Issuer בן 8, 16 ו-64 ספרות. ייצוג ארוך של Issuer ID קצר עם אפסים מובילים נמצא כאותו 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 |
| מזהה מסמך | 4 WORD | 16 | 0x0000000000000000 |
| מזהה גרסה | 2 WORD | 8 | 0x00000003 |
| hash תוכן | 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 זהה.
- כללי מזהה הגרסה (מ-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 ID>/latest.geul Codec, האחרון
/.well-known/geul/<Issuer>/codecs/<Codec ID>/<מזהה גרסה>.geul Codec, גרסה מסוימת
/.well-known/geul/<Issuer>/codecs/<Codec ID>/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/<hash תוכן>.geul חיפוש לפי hash תוכן
דוגמה: /.well-known/geul/0x00000002/docs/0x0000000000000000/latest.geul
- הנתיב עוקב אחר
.well-knownשל RFC 8615. geul.org ופרסום פרטי משתמשים באותו נתיב ורק הדומיין שונה. הסיומת שיש לרשום היאgeulאחת. - רשימת Issuer היא
issuers/. Codec, מסמך רגיל ו-hash מתפצלים תחת תיקיית ה-Issuer ל-codecs/<Codec ID>/, docs/<מזהה מסמך>/ו-hashes/. גם לרשימת Issuer יש גרסה 1 ואילך ו-versions.geul(מסמכי רשימה). latest.geulהוא שם שמור וכינוי. הוא אינו נשמר. מחפשים ב-versions.geulבאותו מקום את הגרסה האחרונה ומוציאים את הבייטים של אותה גרסה כפי שהם. אין ניתוב מחדש (redirect). כלlatest.geulשל רשימת Issuer, Codec ומסמך הם כך.- הכתובת הקנונית של גרסה אחת היא
/<Issuer>/docs/<מזהה מסמך>/<מזהה גרסה>.geul. ל-Codec היא/<Issuer>/codecs/<Codec ID>/<מזהה גרסה>.geul. כתובת אחרת שמחזירה אותו תוכן מצביעה על הכתובת הקנונית ב-Link: rel=canonical. - כתובת של גרסה מסוימת וכתובת של hash תוכן הן בלתי משתנות. אפשר להציב כתובת בלתי משתנה במטמון קבוע וב-CDN. הצד המקבל מאמת באמצעות hash התוכן שברשימת הגרסאות (או ברשומת הנעילה).
- כדי לחפש לפי hash תוכן צריך להכיר את ה-Issuer. אין חיפוש גלובלי לפי hash בלבד.
- למסמך Codec אין מזהה מסמך. הוא מצביע על עצמו ועל גרסתו באמצעות CODEC-POINTER (Issuer, Codec ID, מזהה גרסה).
- ID מתחיל תמיד ב-
0x. לכן שמות שמורים (issuers, codecs, docs, hashes, latest.geul, versions.geul) או שמות שאדם נתן אינם מתנגשים ב-ID, גם אם הם מילים שכולן hex כמוaddו-cafe. - המיקום (מאיזה שרת מורידים) אינו נכנס לתוכן המסמך. אם ייכנס, hash התוכן ישתנה כשהכתובת תשתנה. המיקום נקבע בהגדרות של הצד המוריד את המסמך.
צורת הפרסום והחיפוש
- הכתובת היא כתובת לוגית. גוף הפרסום יכול להוציא קבצים בודדים או 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) // פורמט שאינו אחד מ-10 הוא 404 (לא קיים)
Fetch(ctx, Addr) ([]byte, error) // geul get = ParseAddr → Fetch → פלט סטנדרטי
ציון פורמט
- כתובת פרסום מסתיימת ב-
.geulוהיא בינארית (application/vnd.geul). - הנוסח הבינארי הוא הנוסח הקנוני של המסמך. hash תוכן וחתימה מחושבים מהבינארי בלבד.
מסמכי רשימה
מסמך הרשימה הוא רשימת ה-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>/docs/<מזהה מסמך>/באף Issuer (404). מזהה המסמך השמור האחר0x0000000000000000הוא מסמך אינדקס הגדרות המונחים של אותו Issuer וממוקם תחתdocs/(Issuer ופרסום). - במסמך רשימה לא מציבים
DOC-ID. של מה זו רשימה אומר ה-DOC-POINTER ברשומה (DOC-ID). - מסמכים ו-Codec נמצאים ישירות לפי ID שחושב מהרשומה, בלי רשימה (שם מסמך).
שם דומיין
שם דומיין אינו כתובת URL של פרסום. כתובת שבה כתבו דומיין במקום <Issuer> או שם במקום ID היא מחוץ לעשרת הפורמטים שלעיל ולכן 404 (לא קיים). גם אין ניתוב מחדש (redirect) משם לכתובת ID.
- שם דומיין הוא קלט של המפרש ושל ה-CLI. המפרש ממיר דומיין ל-Issuer ID באמצעות ה-BIND ברשימת ה-Issuer
issuers/. ה-ID שהומר נרשם ברשומת הנעילה. אין כתובת של שם מסמך (שם מסמך). - הכתובת הקנונית, מפתח המטמון ויעד החתימה הם כתובת ה-ID.
- דומיין נכתב באותיות קטנות, ודומיין בינלאומי (IDN) נכתב בצורת IDNA (punycode). לא מוסיפים
.בסוף. - Issuer של 16 WORD, שאין לו רישום, וסביבה מנותקת רשת שאינה מגיעה ל-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.
- השם הוא דומיין שעבר הוכחת בעלות על דומיין. הוא באותיות קטנות, ודומיין בינלאומי (IDN) נכתב ב-IDNA (punycode). שם אחד נקשר ל-Issuer אחד בלבד.
- שם התצוגה של ה-Issuer שנקרא בידי בני אדם (לפי שפה) מוצמד לאותו Subject כ-LABEL של היגד.
- geul.org (ה-Issuer GEUL) חותמת, ובעת שינוי מוסיפים ואין מתקנים (אותו כלל שרשרת כמו ברשימת גרסאות).
שם מסמך
אין כתובת של שם מסמך. מסמכים ו-Codec נמצאים לפי ID.
- אין אינדקס שממיר שם מסמך או שם Codec ל-ID. גם ברשימת הגרסאות לא מציבים BIND של שם מסמך (PUBLICATION).
- אינדקס שבני אדם מעיינים בו נבנה בידי כלי (viewer) מתוך מצאי ה-pack.
- הכתובת הקנונית, מפתח המטמון ויעד החתימה הם כתובת ה-ID. IMPORT וציטוט בתוך מסמך נעשים באמצעות ID בלבד.
- כותרת הנקראת בידי בני אדם (לפי שפה) מוצמדת כ-LABEL של היגד.
מסמך שנמחק
- גם כתובת של גרסה שבוטלה במחיקה משפטית או במחיקה מכוח סמכות (TOMBSTONE) היא 404 (לא קיים), כמו כל כתובת שאינה קיימת.
- גרסה שהומלץ להפסיק את השימוש בה (DEPRECATION) אינה 404. היא ממשיכה להיות מוגשת בכתובת הגרסה שלה.
- מחיקה נשארת ברשימת הגרסאות כרשומת TOMBSTONE (DOC-POINTER של אותה גרסה, קטגוריית הסיבה).
שכבה
GEUL מבטאת כמסמכי GEUL גם מוצא, Meta ורשימות. המינימום הדרוש לקריאתם מובנה במפענח כדי לשבור את המעגליות. כל שכבה נשענת רק על השכבות שמתחתיה.
| שכבה | תוכן | נשענת על |
|---|---|---|
| שכבה 0 | כללים מובנים במפענח: מסגור, hash תוכן, אימות חתימה, 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 ID>/versions.geul, לרשימת Issuer issuers/versions.geul). פורמט הרשומות ומבנה המסמך נקבעים ב-PUBLICATION.
DOC-*
SPEC-VERSION
PARENT hash התוכן של רשימת הגרסאות הקודמת
RECORDED-AT הזמן שבו הוצאה הרשימה הזו
NEXT-LOCAL-ID ה-LOCAL ID הבא להקצאה
SIGNATURE חתימת גוף הפרסום
BODY
PUBLICATION #1 מסמך@1 hash תוכן
PUBLICATION #2 מסמך@2 hash תוכן
DEPRECATION #3 מסמך@1
…
END
| Edge | משמעות |
|---|---|
| PUBLICATION | מפרסם גרסה אחת של מסמך ואת hash התוכן שלה |
| DEPRECATION | מסמן המלצה להפסיק שימוש בגרסה שפורסמה. היא ממשיכה להתפרש |
| TOMBSTONE | מוחק גרסה שפורסמה (מחיקה משפטית או מכוח סמכות). רושם קטגוריית סיבה |
- הרשומות רק מתווספות. אין מתקנים, מוחקים או משנים סדר. גם deprecate ומחיקה מוסיפים רשומה. רשימה חדשה משאירה בראשה את ה-BODY של הרשימה הקודמת כפי שהוא ומוסיפה רשומות, והרשימות מתחברות בשרשרת hash של
PARENT. - הכוונה היא שאין מתקנים את רישום הפרסום, וזה שונה מתיקון תוכן המסמך (מסמך). המצב הנוכחי של גרסה מחושב מהחלת הרשומות לפי הסדר.
- מזהי הגרסה עולים מ-1 ללא חורים. אין מפרסמים אותו תוכן שוב.
- הגרסה האחרונה היא הגרסה הגבוהה ביותר שאינה מומלצת להפסקה ואינה נמחקה.
- ברשומה לא מציבים זמן. זמן הפרסום הוא ה-
RECORDED-ATשל הרשימה הראשונה שבה נכללה הרשומה. - ברשימת גרסאות לא מציבים
DOC-ID. ה-DOC-POINTER ברשומה (מזהה מסמך, ולרשימת Issuer מזהה המסמך השמור) אומר של מה זו רשימה. - רשימת גרסאות אינה מציבה IMPORT ומשתמשת רק ב-Codec של שכבה 0. ב-BODY יש רק PUBLICATION·DEPRECATION·TOMBSTONE.
- רשימות גרסאות קודמות מצוינות רק באמצעות hash תוכן (
<Issuer>/hashes/<hash תוכן>.geul), וההיסטוריה מתחברת בשרשרתPARENT. - הכתובות המשתנות הן
latest.geulו-versions.geul. מכיוון שאי אפשר ליצור מסמך ממצביע משתנה, מאמתים באמצעות החתימה, ה-RECORDED-ATוה-PARENTשל הרשימה שהתקבלה.
גורם החתימה
| חתימה | גורם | יעד |
|---|---|---|
| חתימת מסמך | ה-Issuer של המסמך | hash התוכן של המסמך (Issuer ופרסום) |
| חתימת רשימה | גוף הפרסום שהקצה את מזהי הגרסה | hash התוכן של רשימת הגרסאות |
- בפרסום ב-geul.org, geul.org (ה-Issuer GEUL), ובפרסום פרטי, אותו Issuer, מקצה את מזהי הגרסה וחותם על הרשימה.
- המחבר אחראי לתוכן, וגוף הפרסום אחראי למספר ולסדר.
אימות
- החתימה יוצאת מ-hash התוכן, ולכן גם אם מוחקים אותה ה-hash נשאר. לכן מאמתים לא ב״אם יש חתימה בודקים״ אלא ב״חייבת להיות חתימה של המפתח שנקבע״. המפתח הנדרש נקבע בהגדרות האמון של המפרש וברשומת הנעילה.
- המפרש רושם ברשומת הנעילה את hash התוכן של הרשימה האחרונה שראה. אם ה-hash הזה אינו בשרשרת
PARENTשל רשימה חדשה שהתקבלה, דוחים אותה (מניעת הרצה לאחור והסתעפות). - מראות וסביבות מנותקות רשת מעתיקות יחד את שרשרת רשימות הגרסאות. די במפתח ציבורי כדי לאמת במצב לא מקוון.
- מסמך שהתקבל מאומת באמצעות hash התוכן, מכל מוצא שבא. אין צורך לסמוך על המוצא.
פתרון תלויות
- מסמך רושם מסמכי תלות ב-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 שמספק מיקום.