مسجل بوابة القرار أصل أساسي
Docs
وثائق المسجل

توثيق تسجيل الإثبات والأدلة المقاومة للتلاعب.

وثائق المنتجات الأخرى

هندسة سير عمل مشغل CLI ومسجل

Audience: Engineers extending CLI behavior and operators automating Recorder مع مخرجات الآلة.

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

  1. نظرة عامة تنفيذية
  2. واجهة الأوامر والتوجيه
  3. نموذج دقة وقت التشغيل
  4. عمليات العمل
  5. نموذج الإخراج والتعريب
  6. حدود الإدخال الصعبة وسلوك الفشل المغلق
  7. دلالات رمز الخروج
  8. مرجع متقاطع ملف بملف

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

recorder هو الحدود التشغيلية لعمليات Recorder المحلية. إنه ينظم recorder و recorder-store مع مجموعات أوامر صريحة ووضع JSON حتمي للأتمتة.

F:crates/recorder-cli/src/main.rs F:crates/recorder-cli/src/main_cli_types.rs F:crates/recorder-cli/src/commands.rs L19-L29 F:crates/recorder-cli/src/support.rs L19-L23

واجهة الأوامر والتوجيه

مجموعات الأوامر على المستوى الأعلى:

  • recorder (عمليات المقطع + الظرف)،
  • recorder envelope record-with-attachments (استيعاب المرفقات)
  • recorder signer (دورة حياة دوران مفتاح التوقيع الصريح)،
  • استعلام (استرجاع الظرف)،
  • bundle (بناء/تحقق/تفتيش)،
  • config (فحوصات تكوين وقت التشغيل)،
  • contract (أداة العقد المولدة generate/check)،
  • assurance (عمق بدء التشغيل، وضع جذر الثقة، وفحوصات بوابة OSS)،
  • decision-gate (استيعاب التركيب عبر محول الإنتاج)،
  • otel (استيراد بيانات OTel JSON عبر محول الإنتاج)،
  • doctor (تشخيص المتجر والقطاعات النشطة).

F:crates/recorder-cli/src/main_cli_types.rs

تستخدم بنية الإرسال أجهزة توجيه فرعية صريحة بدلاً من المطابقة الضمنية للمُعالج، مع تقسيم تنفيذات الأوامر حسب منطقة سير العمل. F:crates/recorder-cli/src/main.rs F:crates/recorder-cli/src/commands.rs L19-L29

نموذج دقة وقت التشغيل

تُحل إعدادات وقت التشغيل وفقًا للأولوية:

  1. علامات CLI،
  2. ملف التكوين الاختياري،
  3. الافتراضات.

الإعدادات الافتراضية المهمة:

  • store_path: recorder.db
  • recorder_id: recorder-cli
  • schema_version: المخطط الحالي
  • auto_seal: لا شيء ما لم يتم تقديم عدد و/أو مدة صريحة
  • query.limit: الافتراضي 1000، الحد الأقصى 10000
  • security_profile: secure

نموذج وقت تشغيل الموقّع:

  • تحميل الموقّع المدرك للملف الشخصي (secure, standard, dev),
  • افتراضي آمن يتطلب مواد مفتاح مشفرة PKCS#8،
  • خيار صريح للتقليل من استخدام نص عادي/بذور التطوير في dev,
  • تم الاحتفاظ ببيانات التعريف الخاصة بالدوران (store_meta) مع فحوصات الاتساق.

F:crates/recorder-cli/src/main.rs F:crates/recorder-cli/src/main_cli_types.rs F:crates/recorder-cli/src/support/runtime.rs L20-L122 F:crates/recorder-cli/src/support/runtime.rs L247-L556

اختيار خلفية المتجر:

عمليات العمل

تتوافق سير العمل التمثيلية مباشرة مع معالجات الأوامر:

  • فتح/تسجيل/إغلاق/حالة/قائمة دورة حياة الجزء،
  • تسجيل المظاريف مع ملف مرفق ومدخلات base64 مضمنة (record-with-attachments),
  • explicit key rotation (recorder signer rotate) with deterministic تدوير المفاتيح بشكل صريح (recorder signer rotate) مع إصدار دليل system.adapter.key_rotated المحدد،
  • استعلامات الظرف المصفاة مع دعم المؤشر،
  • بناء الحزمة من JSON المحدد، التحقق (اختياريًا مع جذر الثقة)، والتفتيش،
  • توليد/تحقق من توقعات العقد (contract generate|check),
  • فحوصات نشر الضمان (assurance startup|trust-root|gates),
  • إدخال نص قرار البوابة / تثبيت حزمة التشغيل من خلال محول الإنتاج.
  • استيراد تثبيت تصدير OTel JSON من خلال محول الإنتاج.

F:crates/recorder-cli/src/commands/recorder.rs L20-L524 F:crates/recorder-cli/src/commands/query.rs L20-L88 F:crates/recorder-cli/src/commands/bundle.rs L20-L170 F:crates/recorder-cli/src/commands/admin.rs L20-L194

تغطي اختبارات التكامل سير العمل الأساسي وحالات الفشل المغلقة. F:crates/recorder-cli/tests/commands.rs F:crates/recorder-cli/tests/commands/core.rs F:crates/recorder-cli/tests/commands/query_and_rotation.rs F:crates/recorder-cli/tests/commands/attachments_and_dg.rs

نموذج الإخراج والتعريب

أوضاع الإخراج:

  • --json: حمولات هيكلية حتمية للأتمتة،
  • وضع النص: رسائل مشغل محلية.

عقد استعلام وضع JSON الآن يصدر:

  • {"envelopes": [...], "next_cursor": ..., "applied_limit": ...}.

فشل وضع JSON يصدر غلافًا حتميًا:

  • {"error": "<message>"}.

حل مشكلة اللغة:

  • --lang يتجاوز RECORDER_LANG،
  • supported locales are generated from catalog files under crates/recorder-cli/i18n/locales/*.toml,
  • قيم الموقع غير المعروفة تفشل بإغلاق مع خروج غير صفري،
  • تظل اللغة الافتراضية en فقط عندما لا يتم تحديد اللغة.

ضمانات سلامة التوطين:

  • build-time catalog validation enforces locale-tag uniqueness, default-locale presence, exact key parity against en, and exact placeholder-set parity for كل مفتاح عبر جميع المناطق،
  • message templates are generated into typed keys/macros and translation table code (OUT_DIR/i18n_generated.rs),
  • runtime translation paths are strict and fail closed on unknown keys, عدم تطابق مجموعة العناصر النائبة، أو العناصر النائبة غير المحلولة،
  • لا يوجد تراجع صامت إلى معرفات المفاتيح أو الإنجليزية للترجمات المفقودة،
  • locale provenance metadata is mandatory (machine or human_reviewed) and تقوم إعدادات الآلة بإصدار إخلاء مسؤولية صريح أثناء وقت التشغيل،
  • JSON output payload contracts remain locale-neutral and stable across locale اختيار.

تغطية اللغة تشمل:

  • recorder الملف التنفيذي الرئيسي،
  • recorder_oss_assurance_checks,
  • recorder_oss_assurance_packet.

F:crates/recorder-cli/src/main.rs F:crates/recorder-cli/build.rs F:crates/recorder-cli/i18n/locales/en.toml F:crates/recorder-cli/i18n/locales/ca.toml F:crates/recorder-cli/src/i18n.rs F:crates/recorder-cli/src/support/util.rs F:crates/recorder-cli/src/bin/recorder_oss_assurance_checks.rs F:crates/recorder-cli/src/bin/recorder_oss_assurance_packet.rs F:crates/recorder-cli/tests/i18n_compile_fail.rs F:crates/recorder-cli/tests/commands/core.rs

حدود الإدخال الصعبة وسلوك الفشل المغلق

تفرض واجهة سطر الأوامر قراءات ملفات محدودة:

  • config: 1 ميغابايت,
  • payload JSON: 4 ميغابايت,
  • ملف المرفق/حمولة مضمنة: 16 ميغابايت,
  • JSON بوابة القرار: 8 ميغابايت،
  • OTel fixture JSON: 16 ميغابايت،
  • محدد JSON: 1 ميغابايت,
  • حزمة JSON: 32 ميغابايت،
  • trust-root JSON: 1 ميغابايت,
  • ملف مفتاح الموقّع: 64 KiB,
  • مادة عبارة مرور الموقّع: 1 KiB.

F:crates/recorder-cli/src/main.rs

يتم رفض المدخلات الكبيرة قبل التحليل/المعالجة. F:crates/recorder-cli/src/support/util.rs L225-L277

يمكن لـ bundle verify تحميل جذر ثقة صريح، وتوجيهه إلى Verifier::with_trust_root، وتصدير نص التحقق الحتمي بتنسيق JSON عبر --verdict-transcript-output. F:crates/recorder/src/verification_transcript.rs F:crates/recorder-cli/src/commands/bundle.rs L74-L116

مجموعة أوامر assurance توفر فحوصات افتراض OSS صريحة:

  • assurance startup executes runtime bootstrap and startup-verification path يتحقق من التأكيدات الاختيارية للحد الأدنى من العمق،
  • assurance trust-root يتحقق من افتراضات تحليل/سياسة/مجموعة المفاتيح الخاصة بجذر الثقة،
  • assurance gates executes contract check gate semantics directly. F:crates/recorder-cli/src/commands/assurance.rs

تغطية اختبار النظام الآن تتحقق من:

دلالات رمز الخروج

  • تعود أخطاء الأوامر العامة برمز الخروج 1 عبر emit_error.
  • JSON-mode command errors still return exit code 1 with machine-parseable لا تزال أخطاء أوامر وضع JSON تعيد رمز الخروج 1 مع حمولة قابلة للتحليل بواسطة الآلة {"error": ...}.
  • bundle verify يُرجع رمز الخروج 2 عندما تكون حالة الحكم غير صالحة.

F:crates/recorder-cli/src/support/util.rs L343-L345 F:crates/recorder-cli/src/commands/bundle.rs L112-L114

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

المنطقةالملفالملاحظات
إدخال CLI وتوجيههcrates/recorder-cli/src/main.rs, crates/recorder-cli/src/main_cli_types.rsنموذج Clap، تدفق locale/bootstrap، توجيه التوجيه على المستوى الأعلى.
معالجات الأوامرcrates/recorder-cli/src/commands.rsتجميع وحدات معالجة مجموعة الأوامر.
معالجات المسجلcrates/recorder-cli/src/commands/recorder.rsعمليات الشريحة/الغلاف ومنطق تدوير الموقّع.
معالجات الاستعلام والحزمةcrates/recorder-cli/src/commands/query.rs, crates/recorder-cli/src/commands/bundle.rsمرشحات الاستعلام وعمليات بناء/تحقق/تفتيش الحزمة.
معالجات الإدارةcrates/recorder-cli/src/commands/admin.rsتحقق من التكوين، تشخيص الطبيب، أوامر العقد.
معالجات التكاملcrates/recorder-cli/src/commands/integration.rsتدفقات إدخال Decision Gate و OTel.
مساعدات وقت التشغيل والمرافقcrates/recorder-cli/src/support.rs, crates/recorder-cli/src/support/runtime.rs, crates/recorder-cli/src/support/util.rsحل وقت التشغيل، سياسة الموقّع، التحليل، إدخال/إخراج محدود، مساعدات الإخراج.
كتالوج i18n والتوليدcrates/recorder-cli/build.rs, crates/recorder-cli/i18n/locales/en.toml, crates/recorder-cli/i18n/locales/ca.toml, crates/recorder-cli/src/i18n.rsكتالوجات locale التي تم التحقق منها عند البناء، مفاتيح/ماكرو محددة، بيانات التعريف، وعرض صارم بدون تراجع.
ثنائيات OSS المساعدةcrates/recorder-cli/src/bin/recorder_oss_assurance_checks.rs, crates/recorder-cli/src/bin/recorder_oss_assurance_packet.rsبدء تشغيل locale (--lang و RECORDER_LANG) والأسطح المحلية للاستخدام/الأخطاء مع حمولات JSON محايدة للغة.
اختبارات تكامل CLIcrates/recorder-cli/tests/commands.rs, crates/recorder-cli/tests/commands/helpers.rs, crates/recorder-cli/tests/commands/core.rs, crates/recorder-cli/tests/commands/query_and_rotation.rs, crates/recorder-cli/tests/commands/attachments_and_dg.rsتغطية سير العمل من البداية إلى النهاية لسمات CLI.
تكامل مولد العقدcrates/recorder-contract/src/lib.rsسلطة الأثر الناتج المحدد التي تستهلكها أوامر عقد CLI.
مجموعة عمليات اختبار النظامsystem-tests/tests/suites/operations/mod.rs, system-tests/tests/suites/operations/query.rs, system-tests/tests/suites/operations/config.rs, system-tests/tests/suites/operations/locale.rs, system-tests/tests/suites/operations/contract.rsيتحقق من مطابقة التحقق من التكوين وسلوك التحقق من JSON للصفحات/الحدود.
مجموعة اختبار المسجل للنظامsystem-tests/tests/suites/recorder.rsيتحقق من عدد/مدة/دورة الحياة المدمجة وسلوك تسجيل المرفقات.
مجموعة اختبار الأمان للنظامsystem-tests/tests/suites/security.rs, system-tests/tests/suites/security_support.rs, system-tests/tests/suites/security_limits.rs, system-tests/tests/suites/security_signer.rs, system-tests/tests/suites/security_contract_bundle.rsيتحقق من سلوك حدود CLI المغلقة عبر الحدود، عدائية المرفقات، سياسة الموقّع، استرداد التدوير، سلامة مسار العقد، ومدخلات الحزمة العدائية.
مجموعة اختبار Decision Gate CLI للنظامsystem-tests/tests/suites/integration_decision_gate.rs, system-tests/tests/suites/integration_decision_gate_support.rs, system-tests/tests/suites/integration_decision_gate_contract_shape.rs, system-tests/tests/suites/integration_decision_gate_ingest.rsيتحقق من نجاح إدخال fixture CLI لمحول الإنتاج وسلوك عدم المطابقة الصارم.
حزمة محول OTelcrates/recorder-otel-adapter/src/lib.rsتنفيذ خريطة إدخال JSON OTel للإنتاج التي تستهلكها أوامر تكامل CLI.