بنية تخزين المسجل

Audience: Engineers changing persistence logic, query semantics, schema, الجمهور: المهندسون الذين يغيرون منطق الاستمرارية، دلالات الاستعلام، المخطط، أو واجهات التخزين.

جدول المحتويات

نظرة عامة تنفيذية
عقود سمات التخزين
خلفية في الذاكرة
SQLite الخلفية
مخطط SQLite والفهرسة
فرض استمرارية السلسلة
دلالات الاستعلام والترقيم
الفساد ومعالجة الأخطاء
مرجع متقاطع ملف بملف

نظرة عامة تنفيذية

recorder-store يوفر تجريد الاستمرارية واثنين من الواجهات الخلفية الملموسة:

InMemoryStore للاختبار الحتمي والتنفيذ المحلي،
SqliteStore لعمليات دائمة مع WAL وفحوصات معاملات.

كلاهما ينفذ عقود سمات مشتركة لعمليات الظرف، والمرفق، والجزء. F:crates/recorder-store/src/lib.rs L11-L37 F:crates/recorder-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/recorder-store/src/traits.rs L43-L101 F:crates/recorder-store/src/traits.rs L107-L138 F:crates/recorder-store/src/traits.rs L144-L206

توجهات استيعاب السايدكار الحالية:

sidecar mutating ingest uses writer-owned SQLite transaction logic over streams + segments stream identity columns to maintain one open segment لكل مفتاح دفق،
this stream-scoped segment lifecycle is intentionally decoupled from legacy trait-level single-active-segment assumptions used by recorder-era APIs. F:crates/recorder-store/src/traits.rs L43-L101 F:crates/recorder-sidecar/src/ingest.rs

خلفية في الذاكرة

InMemoryStore يستخدم خرائط ومتجهات محمية بالقفل، مما يحافظ على فحوصات الثبات ولكن دون ضمانات اتساق عند التعطل. F:crates/recorder-store/src/memory.rs L12-L16

سماحيات السلوك:

يتحقق من حالة المقطع واستمرارية السلسلة عند الإضافة،
يحتفظ بمعرفات الظرف الأول/الأخير وتحديثات رأس السلسلة،
يفرض قواعد إنشاء مقاطع مفتوحة واحدة وعدم تكرار معرف المقطع،
يدعم قائمة المقاطع المحددة بشكل حتمي بواسطة created_at،
يفرض ترتيب استعلامات الحزمة المحدد بواسطة segment_id ثم التسلسل.

F:crates/recorder-store/src/memory.rs L124-L180 F:crates/recorder-store/src/memory.rs L317-L407

SQLite الخلفية

SqliteStore يوجه جميع عمليات قاعدة البيانات من خلال خيط اتصال مخصص (SqliteConnection) للحفاظ على دلالات الكتابة الفردية بأمان عبر المتصلين غير المتزامنين. F:crates/recorder-store/src/sqlite/mod.rs L12-L22 F:crates/recorder-store/src/sqlite/connection.rs L12-L21

SqliteConnection::execute يستخدم sync_channel المحدود + قنوات oneshot لربط الشيفرة غير المتزامنة مع عمليات rusqlite المتزامنة. قبول الطابور واضح: فشل تشبع الطابور يغلق مع StoreError::ConcurrencyConflict بدلاً من السماح بنمو العمل في الذاكرة بدون حدود. F:crates/recorder-store/src/sqlite/connection.rs L42-L136 F:crates/recorder-store/src/sqlite/connection.rs L167-L222

اكتشاف الشريحة النشطة (get_active_segment) الآن يفشل بشكل مغلق عندما تكون الحالة المحفوظة تالفة لتحتوي على عدة شرائح مفتوحة. هذا يمنع سلوك الاسترداد الغامض من اختيار شريحة مفتوحة عشوائية. F:crates/recorder-store/src/sqlite/segment_ops.rs

SqliteStore يعرض أيضًا مساعدات بيانات وصفية محددة على store_meta (get_meta, set_meta, set_meta_batch) لحالة وقت التشغيل الحتمية مثل علامات عدم التكرار لدوران مفتاح الموقّع. F:crates/recorder-store/src/sqlite/mod.rs

تدعم الآن تحسين فتح SQLite عناصر تحكم زمن التشغيل الصريحة والمصادق عليها:

وضع المتانة المتزامن (FULL افتراضي)،
صفحات WAL نقطة التحقق التلقائي (افتراضي صريح)،
optional busy-timeout. F:crates/recorder-store/src/sqlite/mod.rs F:crates/recorder-store/src/sqlite/schema.rs F:crates/recorder-store/src/sqlite/mod.rs

مخطط SQLite والفهرسة

تهيئة تمكّن:

وضع WAL،
المفاتيح الأجنبية،
جدول بيانات التعريف الخاص بالمخطط مع بوابة إصدار المخطط المغلقة (schema_version=2)،
تم تطبيع segments، envelopes، attachments، وجداول التقاطع،
writer/projection tables: streams, idempotency_entries, query_projection_envelopes,
stream identity columns on segments and envelopes used by sidecar ترتيب وقت التشغيل للكاتب حسب التدفق وثوابت الدوران،
فهارس لأنماط الغلاف/الجزء/استعلام-الإسقاط الحتمية.

F:crates/recorder-store/src/sqlite/schema.rs L111-L144 F:crates/recorder-store/src/sqlite/schema.rs L43-L105

فرض استمرارية السلسلة

كلا النظامين الخلفيين يفرضان التحقق من صحة سلسلة الوقت المضافة باستخدام إعادة حساب رأس السلسلة المتوقع ومقارنة في وقت ثابت.

التحقق من الإلحاق في الذاكرة: F:crates/recorder-store/src/memory.rs L140-L158

تحقق من صحة الإلحاق في SQLite محصور في نطاق المعاملات:

تحقق من وجود الجزء وأنه مفتوح،
إعادة حساب تجزئة السلسلة المتوقعة،
رفض عدم التطابق،
إدراج صفوف الظرف + مرفقات الظرف،
تحديث بيانات المقطع بشكل ذري.

F:crates/recorder-store/src/sqlite/envelope_ops.rs L42-L141

دلالات الاستعلام والترقيم

تدعم استعلامات الظرف تصفية متعددة الحقول بالإضافة إلى استمرار المؤشر والحد. تستخدم استعلامات نطاق التدفق الجانبي query_projection_envelopes و ORDER BY stream_sequence ASC ضمن نطاق (tenant_id, recorder_id). تستمر استعلامات الظرف القطاعي في الترتيب حسب sequence ASC.

F:crates/recorder-store/src/sqlite/envelope_ops.rs L167-L280 F:crates/recorder-store/src/sqlite/envelope_ops.rs L306-L347

يدعم إدراج القطاعات عوامل تصفية الحالة/الوقت/المعرف ويطلب ترتيبها بواسطة created_at ASC, segment_id ASC للحفاظ على ترتيب حتمي تحت طوابع زمنية متساوية عبر الواجهات الخلفية. F:crates/recorder-store/src/sqlite/segment_ops.rs L148-L245

الفساد ومعالجة الأخطاء

StoreError يميز بوضوح بين كسر النزاهة، حالات عدم العثور، تعارضات التزامن، فشل الخلفية، واكتشاف الفساد. F:crates/recorder-store/src/error.rs L36-L103

تتعامل عملية تحليل مقاطع SQLite مع قيم قاعدة البيانات غير الصالحة على أنها فساد (UUID غير صالح، حالة غير معروفة، خوارزمية تجزئة غير معروفة، طوابع زمنية غير صالحة). F:crates/recorder-store/src/sqlite/segment_ops.rs L336-L416

تقوم اختبارات النظام الآن بالتحقق من سلوك الفشل المغلق عند التلاعب بصفوف SQLite المحفوظة باستخدام بيانات UUID/بيانات الجينيس غير الصالحة بين عمليات CLI. F:system-tests/tests/suites/persistence.rs L375-L468

مرجع متقاطع لكل ملف

المنطقة	الملف	الملاحظات
عقود التخزين	`crates/recorder-store/src/traits.rs`	ثوابت سمة التخزين القياسية.
أنواع المقاطع	`crates/recorder-store/src/types.rs`	بيانات التعريف الخاصة بالمقطع وأشكال الفلترة.
الواجهة الخلفية في الذاكرة	`crates/recorder-store/src/memory.rs`	تنفيذ قائم على الخريطة الحتمية.
واجهة SQLite	`crates/recorder-store/src/sqlite/mod.rs`	بناء المتجر وتركيب الواجهة الخلفية.
مساعدات بيانات التعريف لـ SQLite	`crates/recorder-store/src/sqlite/mod.rs`	مساعدات القراءة/الكتابة لـ `store_meta` لاستمرارية حالة وقت التشغيل.
جسر SQLite	`crates/recorder-store/src/sqlite/connection.rs`	جسر غير متزامن مخصص للخيوط.
مخطط SQLite	`crates/recorder-store/src/sqlite/schema.rs`	DDL، الفهارس، إصدار المخطط.
عمليات SQL الخاصة بالظرف	`crates/recorder-store/src/sqlite/envelope_ops.rs`	منطق الاستعلام الإضافي والفلترة المعاملاتي.
عمليات SQL الخاصة بالمقطع	`crates/recorder-store/src/sqlite/segment_ops.rs`	دورة حياة المقطع وفك تشفير بيانات التعريف.
عمليات SQL الخاصة بالمرفقات	`crates/recorder-store/src/sqlite/attachment_ops.rs`	دلالات الإضافة/الحصول/الوجود المعتمدة على المحتوى.
تصنيف الأخطاء	`crates/recorder-store/src/error.rs`	نموذج فشل التخزين المطبوع.