بنية تخزين Arxi
Audience: Engineers changing persistence logic, query semantics, schema, الجمهور: المهندسون الذين يغيرون منطق الاستمرارية، دلالات الاستعلام، المخطط، أو واجهات التخزين.
جدول المحتويات
- نظرة عامة تنفيذية
- عقود سمات التخزين
- خلفية في الذاكرة
- SQLite الخلفية
- مخطط SQLite والفهرسة
- فرض استمرارية السلسلة
- دلالات الاستعلام والترقيم
- الفساد ومعالجة الأخطاء
- مرجع متقاطع ملف بملف
نظرة عامة تنفيذية
arxi-store يوفر تجريد الاستمرارية واثنين من الواجهات الخلفية المحددة:
InMemoryStoreللاختبار الحتمي والتنفيذ المحلي،SqliteStoreلعمليات دائمة مع WAL وفحوصات معاملات.
كلاهما ينفذ عقود سمات مشتركة لعمليات الظرف، المرفق، والجزء. F:crates/arxi-store/src/lib.rs L11-L37 F:crates/arxi-store/src/lib.rs L49-L71
عقود سمات التخزين
عقد التخزين يُعبر عنه كخصائص غير متزامنة ثلاث:
EnvelopeStore: append/get/query/chain-head/segment-envelopes,AttachmentStore: put/get/exists for content-addressed blobs,SegmentStore: إنشاء/إغلاق/قائمة/الحصول على البيانات الوصفية والبداية.
تشمل الثوابت الأساسية سلوك الإضافة فقط، والتحقق من استمرارية السلسلة، وعدم تغيير القطاعات المغلقة. إنشاء القطاع يكون مغلقًا عند الفشل: ترفض المتاجر إنشاء قطاع جديد عندما يوجد بالفعل قطاع مفتوح آخر أو عندما يكون معرف القطاع موجودًا بالفعل. F:crates/arxi-store/src/traits.rs L43-L101 F:crates/arxi-store/src/traits.rs L107-L138 F:crates/arxi-store/src/traits.rs L144-L206
خلفية في الذاكرة
InMemoryStore يستخدم خرائط ومتجهات محمية بالقفل، مما يحافظ على فحوصات الثبات ولكن دون ضمانات اتساق في حالة التعطل. F:crates/arxi-store/src/memory.rs L12-L16
سماحيات السلوك:
- يتحقق من حالة المقطع واستمرارية السلسلة عند الإضافة،
- يحتفظ بمعرفات الظرف الأول/الأخير وتحديثات رأس السلسلة،
- يفرض قواعد إنشاء مقاطع مفتوحة واحدة وعدم تكرار معرف المقطع،
- يدعم قائمة المقاطع المحددة بشكل حتمي بواسطة
created_at، - يفرض ترتيب استعلامات الحزمة المحدد بواسطة
segment_idثم التسلسل.
F:crates/arxi-store/src/memory.rs L124-L180 F:crates/arxi-store/src/memory.rs L317-L407
SQLite الخلفية
SqliteStore يوجه جميع عمليات قاعدة البيانات من خلال خيط اتصال مخصص (SqliteConnection) للحفاظ على دلالات الكتابة الفردية بأمان عبر المتصلين غير المتزامنين. F:crates/arxi-store/src/sqlite/mod.rs L12-L22 F:crates/arxi-store/src/sqlite/connection.rs L12-L21
SqliteConnection::execute يستخدم sync_channel المحدود + قنوات oneshot لربط الشيفرة غير المتزامنة مع عمليات rusqlite المتزامنة. قبول الطابور واضح: فشل تشبع الطابور يغلق مع StoreError::ConcurrencyConflict بدلاً من السماح بنمو العمل في الذاكرة دون حدود. F:crates/arxi-store/src/sqlite/connection.rs L42-L136 F:crates/arxi-store/src/sqlite/connection.rs L167-L222
SqliteStore تعرض أيضًا مساعدات بيانات وصفية محددة على store_meta (get_meta, set_meta, set_meta_batch) لحالة وقت تشغيل حتمية مثل علامات عدم التكرار لتدوير مفتاح الموقّع. F:crates/arxi-store/src/sqlite/mod.rs
مخطط SQLite والفهرسة
تهيئة تمكّن:
- وضع WAL،
- المفاتيح الأجنبية،
- جدول بيانات التعريف للنموذج،
- تم تطبيع
segments،envelopes،attachments، وجداول التقاطع، - فهارس لأنماط استعلام الحزمة/القطاع الحتمية.
F:crates/arxi-store/src/sqlite/schema.rs L111-L144 F:crates/arxi-store/src/sqlite/schema.rs L43-L105
فرض استمرارية السلسلة
كلا النظامين الخلفيين يفرضان التحقق من صحة سلسلة الوقت المضافة باستخدام إعادة حساب رأس السلسلة المتوقع ومقارنة في وقت ثابت.
تحقق من صحة الإضافة في الذاكرة: F:crates/arxi-store/src/memory.rs L140-L158
تحقق من صحة الإلحاق في SQLite محصور في نطاق المعاملات:
- تحقق من وجود الجزء وأنه مفتوح،
- إعادة حساب تجزئة السلسلة المتوقعة،
- رفض عدم التطابق،
- إدراج صفوف الظرف + مرفقات الظرف،
- تحديث بيانات المقطع بشكل ذري.
F:crates/arxi-store/src/sqlite/envelope_ops.rs L42-L141
دلالات الاستعلام والترقيم
استعلامات الظرف تدعم تصفية متعددة الحقول بالإضافة إلى متابعة المؤشر والحد. ترتيب استعلام SQLite هو ORDER BY segment_id, sequence؛ استعلامات الظرف-القطعة ترتب حسب sequence ASC.
F:crates/arxi-store/src/sqlite/envelope_ops.rs L167-L280 F:crates/arxi-store/src/sqlite/envelope_ops.rs L306-L347
يدعم إدراج القطاعات عوامل تصفية الحالة/الوقت/المعرف ويطلب ترتيبها حسب created_at ASC. F:crates/arxi-store/src/sqlite/segment_ops.rs L148-L245
الفساد ومعالجة الأخطاء
StoreError يميز بوضوح بين كسر النزاهة، حالات عدم العثور، تعارضات التزامن، فشل الخلفية، واكتشاف الفساد. F:crates/arxi-store/src/error.rs L36-L103
تحليل مقاطع SQLite يعتبر القيم غير الصالحة في قاعدة البيانات كفساد (uuid غير صالح، حالة غير معروفة، خوارزمية تجزئة غير معروفة، طوابع زمنية غير صالحة). F:crates/arxi-store/src/sqlite/segment_ops.rs L336-L416
تقوم اختبارات النظام الآن بالتحقق من سلوك الفشل المغلق عند التلاعب بصفوف SQLite المحفوظة باستخدام بيانات UUID/بيانات الجينيس غير الصالحة بين عمليات CLI. F:system-tests/tests/suites/persistence.rs L375-L468
مرجع متقاطع لكل ملف
| المنطقة | الملف | الملاحظات |
|---|---|---|
| عقود التخزين | crates/arxi-store/src/traits.rs | ثوابت سمة التخزين القياسية. |
| أنواع المقاطع | crates/arxi-store/src/types.rs | بيانات التعريف للمقطع وأشكال الفلترة. |
| الواجهة الخلفية في الذاكرة | crates/arxi-store/src/memory.rs | تنفيذ قائم على الخريطة الحتمية. |
| واجهة SQLite | crates/arxi-store/src/sqlite/mod.rs | بناء المتجر وتركيب الواجهة الخلفية. |
| مساعدات بيانات التعريف لـ SQLite | crates/arxi-store/src/sqlite/mod.rs | مساعدات القراءة/الكتابة لـ store_meta لاستمرارية حالة وقت التشغيل. |
| جسر SQLite | crates/arxi-store/src/sqlite/connection.rs | جسر غير متزامن مخصص للخيوط. |
| مخطط SQLite | crates/arxi-store/src/sqlite/schema.rs | DDL، الفهارس، إصدار المخطط. |
| عمليات SQL للظرف | crates/arxi-store/src/sqlite/envelope_ops.rs | منطق الاستعلام الإضافي والفلترة المعاملاتي. |
| عمليات SQL للمقطع | crates/arxi-store/src/sqlite/segment_ops.rs | دورة حياة المقطع وفك تشفير بيانات التعريف. |
| عمليات SQL للإرفاق | crates/arxi-store/src/sqlite/attachment_ops.rs | دلالات الإضافة/الحصول/الوجود المعتمدة على المحتوى. |
| تصنيف الأخطاء | crates/arxi-store/src/error.rs | نموذج فشل التخزين المطبوع. |