شخصان يعدّلان الملاحظة نفسها. أحدهما في قطار بلا تغطية، والآخر على مكتبه. وكلاهما يواصل الكتابة. حين يخرج القطار من النفق، كيف يجب أن تكون الملاحظة؟
الجواب الكلاسيكي أن يكون الخادم هو الحَكَم: كل تعديل يذهب إليه، وهو يقرر الترتيب، والعميل الذي بلا اتصال ينتظر. تطبيقات local-first (المحلي أولًا) تقلب هذا. كل جهاز يحمل نسخة كاملة، والتعديلات تُطبَّق فورًا ودون اتصال، والأجهزة تتبادل التغييرات كلما استطاعت الوصول إلى بعضها. والشرط الصعب: بعد تبادل كل شيء، يجب أن تتطابق كل النسخ، مهما كان الترتيب الذي وصلت به التغييرات.
هياكل البيانات التي تضمن ذلك تسمّى CRDT، أي conflict-free replicated data types. و Automerge و Yjs هما المكتبتان المعروفتان المبنيتان عليها. وهما مكتبتان ناضجتان وفيهما تحسينات كثيرة، فقراءتهما طويلة إن كان هدفك أن تفهم كيف تعمل الفكرة.
crdt-sync محرك مزامنة local-first صغير بـ Rust. المستندات أشجار من CRDT، وراءها سجل عمليات (operation log) و vector clocks. النسخ (replicas) تعدّل دون اتصال، وتخزّن العمليات في sqlite، وتتزامن عبر خادم websocket مبني بـ axum ببروتوكول من رسالتين. ويسمّي الـ README جمهورَيه: المطورون الذين يريدون فهم كيف تعمل تطبيقات local-first من الداخل، ومن يحتاج نقطة انطلاق مدمجة ومقروءة لمزامنة مستندات صغيرة بين أجهزة وخادم يتحكم فيه.
ماذا يقدّم
أربعة أنواع CRDT. المستند شجرة مبنية من هذه:
-
LwwRegister، سجل من نوع last-writer-wins: الختم الأعلى (Lamport، ثم replica) هو الذي يفوز. -
LwwMap، خريطة فيها سجل LWW لكل مفتاح. الحذف كتابة لـ "لا شيء"، والقيمة قد تكون قيمة بسيطة أو كائنًا متداخلًا. -
OrSet، مجموعة observed-remove تفوز فيها الإضافة (add-wins): كل إضافة تنشئ وسمًا (tag) فريدًا، والحذف يزيل فقط الوسوم التي رآها. -
Rga، للنص. كل محرف يُدرج بعد محرف مرجعي، والإدراجات المتزامنة في الموضع نفسه تُرتَّب حسب الختم، والحذف يترك شواهد (tombstones).
سجل العمليات. كل تعديل هو Op له معرّف (replica, seq)، حيث seq يعدّ 1 و2 و3 وهكذا لكل نسخة، ومعه ختم Lamport، والكائن المستهدف، والفعل. ولأن الأرقام التسلسلية بلا ثغرات، فإن vector clock من الشكل replica → highest seq يقول بالضبط أي العمليات تملكها نسخة ما. والسؤال "هل رأيت العملية X" مقارنة واحدة.
التسليم بأي ترتيب. الدالة Doc::apply_remote تقبل العمليات بأي ترتيب وأي عدد من المرات. المعروفة تُهمل. والباقية تنتظر في قائمة حتى تُدمج تبعياتها: العملية السابقة من النسخة نفسها، والكائن المستهدف، والمحرف الذي يأتي الإدراج بعده، والوسوم التي رآها حذف من المجموعة.
بروتوكول مزامنة من رسالتين. الرسالة StateVector(clock) يُجاب عنها بـ Ops(missing)، والرسالة Ops(ops) تُدمج. الطرفان يرسلان الـ state vector عند الاتصال، فجولة واحدة في كل اتجاه تكفي ليصير الاثنان محدَّثين. ثم ينقل الخادم العمليات المدمجة حديثًا إلى كل عميل آخر على المستند نفسه.
ترميز مدمج. أعداد LEB128 varint، وجدول نسخ لكل دفعة حتى يأخذ معرّف العملية بايتًا أو اثنين، وأرقام تسلسلية وأختام Lamport مرمَّزة بالفرق (delta)، واختصارات من بايت واحد لحالتي "الكائن نفسه كالعملية السابقة" و"إدراج بعد العملية السابقة". ويذكر الـ README أن كتابة 1000 محرف تُرمَّز في أقل من 8 KB. والـ decoder يرفض المدخل المبتور أو العدائي دون panic ودون حجز ذاكرة مفرط.
خادم وتخزين. خادم axum يقدّم GET /sync/{doc} كـ websocket بإطارات ثنائية (binary frames)، وGET /docs وGET /docs/{doc} بصيغة JSON. يحتفظ بـ Doc واحد في الذاكرة لكل مستند مفتوح، يُحمَّل من sqlite عند أول استعمال، ويضيف العمليات المدمجة إلى sqlite قبل نقلها. والتخزين جدول واحد، ops(doc, replica, seq, body)، يُكتب بـ INSERT OR IGNORE فيكون الحفظ idempotent.
طريقة الاستعمال
ثبّت الملفين التنفيذيين crdt-server وcrdt-cli من GitHub بواسطة Cargo، أو أضِف المكتبة إلى مشروعك:
cargo install --git https://github.com/AbdeldjalilChougui/crdt-sync --locked
cargo add --git https://github.com/AbdeldjalilChougui/crdt-sync
البداية السريعة في الـ README تشغّل خادمًا وعميلين، لكل عميل قاعدة بياناته المحلية، من نسخة محلية للمستودع:
cargo run --release --bin crdt-server -- --listen 127.0.0.1:3030 --db server.db
# two clients, each with its own local database (works offline)
alias c='cargo run -q --release --bin crdt-cli -- --server ws://127.0.0.1:3030 --doc notes'
c --db alice.db insert title 0 "Meeting notes"
c --db alice.db add tags work
c --db alice.db sync
c --db bob.db sync
c --db alice.db set status draft # concurrent edits while "offline"
c --db bob.db set status final
c --db bob.db add tags urgent
c --db alice.db sync && c --db bob.db sync && c --db alice.db sync
c --db alice.db show
c --db bob.db watch # stay connected, print every remote change
curl 127.0.0.1:3030/docs/notes # the server's copy as JSON
Alice و Bob كلاهما يكتب status وهو "غير متصل"، و Bob يضيف وسمًا. وبعد المزامنة، يحمل الاثنان المستند نفسه:
{
"status": "final",
"tags": ["urgent", "work"],
"title": "Meeting notes"
}
السجل احتفظ بواحدة من الكتابتين المتزامنتين، وهي نفسها على كل نسخة. والمجموعة احتفظت بالوسمين معًا.
أوامر الـ CLI هي: show، info، set KEY VALUE، del KEY، insert KEY INDEX TEXT، erase KEY INDEX COUNT، add KEY VALUE، remove KEY VALUE، sync، watch.
وكمكتبة:
use crdt_sync::{Doc, ObjId, ObjKind, sync::sync_pair};
let mut a = Doc::new(1);
let (text, _) = a.map_new(ObjId::Root, "body", ObjKind::Text)?;
a.text_insert(text, 0, "hello")?;
let mut b = Doc::new(2);
sync_pair(&mut a, &mut b); // state vectors, then missing ops
b.text_insert(text, 5, " world")?;
a.map_set(ObjId::Root, "title", "greeting")?;
sync_pair(&mut a, &mut b);
assert_eq!(a.to_json(), b.to_json()); // {"body":"hello world","title":"greeting"}
ما يجب معرفته
قسم الحدود في الـ README طويل وصريح. اقرأه قبل أن تبني على المشروع:
- لا مصادقة ولا صلاحيات في الخادم. كل من يستطيع الوصول إليه يستطيع قراءة كل مستند والكتابة فيه. شغّله على localhost أو خلف proxy يقوم بالمصادقة.
- السجلات تكبر بلا نهاية. لا ضغط (compaction)، ولا snapshots، ولا تنظيف للشواهد. والمستند يُعاد بناؤه بإعادة تشغيل سجله كاملًا.
- النص للملاحظات لا للكتب. البحث في RGA مسح خطي، وهناك عملية لكل محرف.
- مجموعة صغيرة من الأنواع. لا نص منسَّق، ولا قوائم كائنات، ولا عدّادات، ولا نقل. والإنشاء المتزامن لكائن متداخل تحت المفتاح نفسه يُبقي كائنًا واحدًا (LWW)، والتعديلات على الآخر تُخفى.
- تحقق محدود من الأطراف. العمليات القادمة من طرف معطوب، والتي تستهدف كائنًا غير موجود أو من نوع خاطئ، تُسجَّل وتُتجاهل. ولا يوجد تحقق ممن يحق له الكتابة بأي replica id.
-
الأمر
watchيطبع التغييرات البعيدة فقط. والتعديلات تتم بتشغيلات منفصلة للـ CLI.
ما تم اختباره. الأمر cargo test يشغّل 17 اختبار وحدة، و6 خصائص proptest، و4 اختبارات من البداية إلى النهاية (end-to-end). الخاصية الأساسية هي التقارب (convergence): ثلاث نسخ تقوم بإدراجات وحذوف عشوائية في النص، وإضافات وحذوف في المجموعة، وكتابات في السجل، وتعديلات وحذوف في الخريطة، بينما تُسلَّم مجموعات جزئية عشوائية من سجلات بعضها مخلوطة ومكررة. وفي النهاية يستلم الجميع كل شيء بترتيب مبعثر، مرتين. ويجب ألا تبقى عند أي نسخة عمليات معلّقة، وأن تتساوى الساعات والـ JSON، على 300 حالة. وخصائص أخرى تتحقق من تقارب البروتوكول بمزامنات ثنائية في حلقة، ومن أن النص في نسخة واحدة يطابق نموذج Vec<char>، ومن أن البايتات العشوائية والرسائل المقلوبة بعض بتاتها لا تسبب panic في الـ decoder.
والاختبارات من البداية إلى النهاية تغطي دمج تعديلات عميلين دون اتصال، وخادمًا أُعيد تشغيله يقدّم المستند نفسه من sqlite، وعميلًا متصلًا يستلم التعديلات المنقولة، وعمليتَي crdt-cli تعدّلان دون اتصال ثم تتقاربان. وكفحص إضافي، يذكر الـ README أن كسر قاعدة الترجيح في LWW أو ترتيب الإخوة في RGA يجعل خصائص التقارب تفشل بعد حالات قليلة.
لماذا بنيته
فكرة local-first سهلة القول وصعبة التصديق إلى أن ترى كل قطعة: كيف تُعرَّف العملية، ولماذا يكفي vector clock لمعرفة ما ينقص الطرف الآخر، وماذا يعني "انتظر التبعيات" في الكود، وكيف يُدمج نص يكتب فيه شخصان في الموضع نفسه. المكتبات الناضجة تجيب عن كل هذا، لكن وسط كثير من التحسينات.
أردت المسار كله في كود صغير يُقرأ من أوله إلى آخره: الـ CRDT، والسجل، والترميز الثنائي، والتخزين، والبروتوكول، والخادم. وأردت أن يُتحقق من ادّعاء التقارب باختبارات خصائص لا ببضعة أمثلة مختارة باليد، لأن الأخطاء في هذا النوع من الكود تسكن في التداخلات التي لا تخطر على بال أحد.
الكود
الكود والاختبارات موجودة على GitHub: https://github.com/AbdeldjalilChougui/crdt-sync. الرخصة MIT. اعتبره نقطة انطلاق مقروءة للمستندات الصغيرة، مع الحدود المذكورة أعلاه.
نُشر في الأصل على abdeldjalilchougui.biz.
Top comments (0)