هندسة Arxi Sidecar

Audience: Engineers implementing or operating arxi-sidecar as the الجمهور: المهندسون الذين يقومون بتنفيذ أو تشغيل arxi-sidecar كحدود خدمة تسجيل الأدلة القابلة للوصول عبر الشبكة.

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

نظرة عامة تنفيذية
تركيب وقت التشغيل
HTTP السطح والتوجيه
أمان وموارد التحكم
الاستقلالية وأمان إعادة المحاولة
النقل ودورة الحياة
تغليف الحاويات وعمليات Docker
التحقق وتغطية الاختبار
مرجع متقاطع ملف بملف

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

arxi-sidecar هو وقت تشغيل خدمة Arxi HTTP/JSON التي تعرض مسجّل البيانات، واستعلام، وتدفقات العمل للحزم عبر مقبس Unix و/أو مستمعي TCP.

يتكون الـ sidecar من RecorderEngine و BundleBuilder و Verifier ونسخة واحدة من SqliteStore تحت بوابات middleware صريحة لهوية الترابط، والمصادقة، وهوية المؤسسة/السياسة، وإنفاذ الحدود، والتماثل، والتحكم في الوقت المستغرق.

F:crates/arxi-sidecar/src/server.rs L42-L133 F:crates/arxi-sidecar/src/state.rs L29-L56 F:crates/arxi-sidecar-config/src/config.rs

تركيب وقت التشغيل

تدفق بدء التشغيل:

Load and validate TOML config (config_version, api.major_version, تحميل والتحقق من صحة إعدادات TOML (config_version, api.major_version, recorder, transport, security, signer, و limits).
قم بتهيئة التتبع وفتح SqliteStore.
بناء مكونات وقت تشغيل المسجل.
تهيئة مدير الاستمرارية الدائمة على store_meta.
بناء جهاز توجيه axum مع مجموعة من البرمجيات الوسيطة.
ربط مستمعي النقل المكونين وتقديم الخدمة حتى الإلغاء.

F:crates/arxi-sidecar-config/src/config.rs F:crates/arxi-sidecar-config/src/validation.rs F:crates/arxi-sidecar/src/server.rs L43-L247 F:crates/arxi-sidecar/src/idempotency.rs L61-L138

HTTP السطح والتوجيه

الموجه الحالي يعرض:

الاستعلامات: GET /health, GET /startup, GET /ready
Segment lifecycle: POST /v1/segments, POST /v1/segments/seal, دورة حياة المقطع: POST /v1/segments, POST /v1/segments/seal, GET /v1/segments, GET /v1/segments/active
Envelope ingest: POST /v1/envelopes, استلام الظرف: POST /v1/envelopes, POST /v1/envelopes/with-attachments
الاستعلام: POST /v1/query/envelopes
Bundle workflows: POST /v1/bundles/build, POST /v1/bundles/verify, تجميع سير العمل: POST /v1/bundles/build, POST /v1/bundles/verify, POST /v1/bundles/inspect
فحص وقت التشغيل: GET /v1/config

F:crates/arxi-sidecar/src/server.rs L135-L160

سلوك الصحة:

GET /health هو اختبار خفة للحياة يعيد بيانات وصفية عن العملية.
GET /startup is a startup-completion probe returning startup metadata, GET /startup هو استعلام للتحقق من بدء التشغيل يعيد بيانات التعريف الخاصة بالبدء، بما في ذلك startup_verification_depth المكونة.
GET /ready returns readiness state with dependency-aware fail-closed semantics:
- 503 مع السبب=storage_unavailable عندما يفشل الوصول إلى المتجر.
- Optional 503 with reason=request_capacity_exhausted when probes.ready_fail_on_admission_saturation=true and admission/execution اختياري 503 مع reason=request_capacity_exhausted عندما probes.ready_fail_on_admission_saturation=true وتكون إشارات القبول/التنفيذ مستنفدة.
- Optional 503 with reason=enterprise_control_unavailable when probes.readiness_mode=storage_and_enterprise, enterprise mode is enabled, اختياري 503 مع reason=enterprise_control_unavailable عندما يكون probes.readiness_mode=storage_and_enterprise مفعلًا، وضع المؤسسة مفعل، وتف checks جاهزية control-plane تفشل.
- 200 مع ready=true في حالة مستقرة.

F:crates/arxi-sidecar/src/handlers/health.rs L42-L94

أمان وموارد التحكم

بوابة التكوين

تحقق التكوين يكون مغلقًا عند الفشل ويفرض:

تخطيط صارم وإصدار API
معرف المسجل وصلاحية الإغلاق التلقائي،
قيود نقل المضيف/المنفذ،
non-loopback transport requires security.mode=token and keeps يتطلب النقل غير الدائري security.mode=token ويحتفظ بـ require_token_for_non_loopback=true (فشل مغلق)،
token file hardening (security.token_file cannot be a symlink, must be a تقوية ملف الرمز (security.token_file لا يمكن أن يكون رابطًا رمزيًا، يجب أن يكون ملفًا عاديًا، وعلى أنظمة Unix يجب ألا يمنح أذونات للمجموعة/الآخرين)،
قابلية تحليل مفتاح الموقّع،
حدود الأرقام لطلب/رأس/التماثل والتحقق من السقف الصلب،
probe config fail-closed semantics: probes.enterprise_health_path must be absolute/safe and probes.readiness_mode=storage_and_enterprise requires enterprise mode not معطل.

F:crates/arxi-sidecar-config/src/config.rs F:crates/arxi-sidecar-config/src/validation.rs

مكدس البرمجيات الوسيطة

أوامر و تحكمات الوسيط:

حد حجم جسم الطلب (max_request_body_bytes).
طبقة تتبع.
Correlation middleware (server correlation IDs, sanitized client وسيط الترابط (معرفات الترابط على الخادم، x-correlation-id المنقحة، التوافق مع x-request-id القديم).
Auth middleware (Bearer token mode with constant-time compare and RFC 6750 وسيط المصادقة (Bearer token mode مع مقارنة زمن ثابت وبيانات تحدي RFC 6750 في استجابات 401).
Enterprise identity middleware (x-tenant-id, x-principal-id, x-authn-method, optional x-namespace-id, optional writer lease assertion) وسيط هوية المؤسسات (x-tenant-id, x-principal-id, x-authn-method, x-namespace-id الاختياري، تأكيد عقد الإيجار الاختياري للكتابة) لوضعيات المؤسسات الممكّنة.
Enterprise policy middleware (control-plane ingress checks for protected routes plus sidecar boundary hook emission at admission and result وسيط سياسة المؤسسة (تحقق من إدخال خطة التحكم للطرق المحمية بالإضافة إلى إصدار خطاف حدود الحاوية في مراحل admission و result).
Bounds middleware (header bytes, content negotiation, content-length checks, وسيط الحدود (بايتات الرأس، تفاوض المحتوى، فحوصات طول المحتوى، قائمة القبول المحدودة، التزام نشط محدود، مهلة الطلب).

سلوك أولوية الاستقصاء:

/health, /startup, and /ready are exempted from auth, enterprise policy, and bounds gating so liveness/startup/readiness state remains observable under /health و /startup و /ready معفاة من المصادقة، سياسة المؤسسة، وحدود التحكم، بحيث تظل حالة النشاط/البدء/الجاهزية قابلة للرصد تحت الضغط أو فشل السياسات.

F:crates/arxi-sidecar/src/server.rs L155-L160 F:crates/arxi-sidecar/src/middleware/request_id.rs L15-L30 F:crates/arxi-sidecar/src/middleware/auth.rs L21-L84 F:crates/arxi-sidecar/src/control_plane_bridge.rs F:crates/arxi-sidecar/src/middleware/enterprise.rs F:crates/arxi-sidecar/src/middleware/bounds.rs L21-L172

ضوابط حدود المؤسسة

عند تمكين enterprise.mode، يضيف الجانب الجانبي تنفيذًا صريحًا لحدود التحكم مع الحفاظ على دلالات المسجل/الأدلة:

crates/arxi-sidecar/src/control_plane_bridge.rs is a boundary adapter only. It translates sidecar ingress identities/operations into control-plane crates/arxi-sidecar/src/control_plane_bridge.rs هو محول حدودي فقط. يقوم بترجمة هويات/عمليات دخول السايدكار إلى استدعاءات قبول وخطافات في مستوى التحكم؛ لا يقوم بتنفيذ أو تعديل رياضيات أدلة Arxi.
Enterprise config is fail-closed: enabled mode requires token security mode, تكوين المؤسسة هو فشل مغلق: يتطلب وضع التمكين وضع أمان الرمز، وتكوين عنوان URL/الرمز الخاص بالطائرة التحكم، وفحوصات ملف الرمز المقوى.
Enterprise policy gate calls مكالمات بوابة سياسة المؤسسة POST /v1/enterprise/ingress/check قبل عمليات السايدكار المحمية.
Managed-cloud mode enforces writer-lease assertion for mutating operations يفرض وضع السحابة المُدارة تأكيد استئجار الكتاب للعمليات المتغيرة عندما require_writer_lease_header=true.
Sidecar emits deterministic enterprise boundary hooks to POST /v1/enterprise/sidecar/hooks at:
- القبول (السماح/الرفض/خطأ قبل تنفيذ المعالج)،
- نتيجة (السماح/الرفض/خطأ بعد حالة استجابة المعالج).
Hook emission is fail-closed for successful protected operations: if enterprise hook export fails, the sidecar returns an error instead of silently accepting انبعاث الخطاف مغلق في حالة الفشل للعمليات المحمية الناجحة: إذا فشل تصدير الخطاف المؤسسي، فإن الجانب الجانبي يعيد خطأ بدلاً من قبول مسار نجاح غير مدقق بصمت.
Enterprise readiness dependency checks use probes.enterprise_health_path (default /health) against the configured enterprise control-plane base URL when تستخدم فحوصات اعتماد جاهزية المؤسسة probes.enterprise_health_path (افتراضي /health) مقابل عنوان URL الأساسي لواجهة التحكم في المؤسسة المكونة عند probes.readiness_mode=storage_and_enterprise.

F:crates/arxi-sidecar-config/src/validation.rs F:crates/arxi-sidecar/src/control_plane_bridge.rs F:crates/arxi-sidecar/src/middleware/enterprise.rs

عقد الخطأ

تُعاد الأخطاء كـ RFC 9457 تفاصيل المشكلة (application/problem+json) مع رموز خطأ مستقرة، وبيانات إعادة المحاولة، وحقول ارتباط الخادم/العميل.

تفاصيل وضع الأمان:

malformed JSON rejections are normalized to typed bad_request problem details يتم تطبيع رفضات JSON غير الصحيحة إلى تفاصيل مشكلة من نوع bad_request بدلاً من تسرب إخفاقات إطار العمل / مستخرج النص العادي،
server-side (5xx) responses suppress internal detail fields to avoid leaking storage/runtime internals while preserving diagnostics in service استجابات جانب الخادم (5xx) تخفي حقول detail الداخلية لتجنب تسرب تفاصيل التخزين/التشغيل مع الحفاظ على التشخيصات في سجلات الخدمة،
401 unauthorized responses include RFC 6750 WWW-Authenticate challenges.

F:crates/arxi-sidecar/src/error.rs L13-L229 F:crates/arxi-sidecar/src/extract.rs

التماثل وأمان إعادة المحاولة

تستخدم نقاط النهاية المتغيرة حالة عدم التغير المستمرة عبر SqliteStore::store_meta المفاتيح المحددة بواسطة (recorder_id, method, path, idempotency_key) وهاش الطلبات القياسية JCS.

السلوك:

نفس المفتاح + نفس التجزئة: إعادة تشغيل الحالة/الجسم السابق،
نفس المفتاح + تجزئة مختلفة: 409 idempotency_conflict,
storage/index failure: fail-closed idempotency_unavailable.

تكون مدة الاحتفاظ محدودة بواسطة TTL و idempotency_max_entries مع إخلاء محدد.

F:crates/arxi-sidecar/src/idempotency.rs L20-L316

النقل ودورة الحياة

وسائل النقل:

مقبس نطاق يونكس،
مستمع TCP،
كلاهما في نفس الوقت.

دورة حياة وقت التشغيل:

تنظيف مقبس Unix القديم قبل الربط (فشل مغلق تم التحقق من نوع المقبس)،
رمز إلغاء مدفوع بالإشارة،
إيقاف تشغيل سلس لكل مستمع مع فرض مهلة shutdown_drain_seconds
إزالة مقبس Unix في مسار الإيقاف.

F:crates/arxi-sidecar/src/server.rs L163-L262 F:crates/arxi-sidecar/src/shutdown.rs L8-L34

سطح الأمر التشغيلي في ثنائي:

بدء الخدمة العادية مع --config / ARXI_SIDECAR_CONFIG,
healthcheck أمر يدعم أوضاع استكشاف TCP URL و Unix-socket.

F:crates/arxi-sidecar/src/main.rs L18-L175

تغليف الحاويات وعمليات Docker

المستودع الآن يرسل ملف تعريف حاوية جانبية من الطرف الأول تحت docker/sidecar/:

Dockerfile: بناء متعدد المراحل بلغة Rust لصورة تشغيل غير جذرية بدون توزيعة.
docker-compose.yml: local operator profile with explicit UID/GID mapping, docker-compose.yml: ملف مشغل محلي مع تعيين UID/GID صريح، مسارات تكوين/بيانات/تشغيل مثبتة، فحص الصحة، وتعيين منفذ محدود.
config/sidecar.toml: container-oriented baseline config with token-mode config/sidecar.toml: تكوين أساسي موجه للحاويات يتطلب مصادقة بنمط الرمز لوسائل النقل غير المتكررة.
.env.example: canonical environment variable contract for image/tag/paths .env.example: عقد متغيرات البيئة القياسية للصورة/العلامة/المسارات ورسم خرائط UID/GID.

عقد المشغل:

mount token_file as a regular non-symlink file with owner-only permissions قم بتركيب token_file كملف عادي غير مرتبط برمز مع أذونات خاصة بالمالك فقط (0600 على Unix)،
run non-root with host UID/GID mapping so strict token checks remain readable تشغيل غير الجذر مع تعيين UID/GID للمضيف بحيث تظل فحوصات الرموز الصارمة قابلة للقراءة مع تجنب تنفيذ الجذر،
اعتبر docker/sidecar/config/token مادة سرية واحتفظ بها خارج نظام التحكم في الإصدارات.

F:docker/sidecar/Dockerfile F:docker/sidecar/docker-compose.yml F:docker/sidecar/config/sidecar.toml F:docker/sidecar/README.md

التحقق وتغطية الاختبار

تتضمن مجموعة التحقق الحالية للسيارة الجانبية:

config fail-closed validation assertions (port, header hard cap, تأكيدات التحقق من الفشل المغلق في التكوين (المنفذ، الحد الأقصى للرأس، حدود الإغلاق التلقائي)،
سلوك واجهة برمجة التطبيقات للحدود الخاصة بطول المحتوى،
سلوك تطهير معرف الارتباط،
فحوصات حتمية تجزئة طلبات الإيديمبوتنسي القياسية.
generated error-registry compatibility assertions تم إنشاء تأكيدات التوافق لسجل الأخطاء (Docs/generated/arxi/apis/sidecar.errors.json مقابل قاعدة التشغيل الأساسية).
restart-boundary idempotency replay/conflict integration checks over real إعادة تشغيل حدود التكرار/التكامل للتحقق من الصراعات على الجانب الحقيقي subprocess + استمرارية SQLite.
contract hardening checks for RFC 9457 payload shape, RFC 6750 auth challenge فحوصات تعزيز العقد لشكل الحمولة RFC 9457، ورؤوس تحدي المصادقة RFC 6750، وانتشار رؤوس الترابط.
probe hardening checks for unauthenticated probe routes and startup probe فحص تقوية المسارات غير المعتمدة لفحص البروبي والاستجابة لعقد بدء التشغيل.
readiness hardening checks for admission saturation fail-closed behavior and فحوصات تعزيز الجاهزية لسلوك الفشل المغلق عند تشبع القبول وانتقالات وضع الاعتماد على مستوى التحكم المؤسسي.
generated sidecar contract compatibility gates (openapi/errors/enums/examples/compat) تم فرض بوابات التوافق لعقد الجانب المولد (openapi/errors/enums/examples/compat) في تنسيق generate/check.
optional release perf gate (ARXI_SIDECAR_PERF_GATE=1) for SLO promotion enforcement, including generation of target/sidecar-perf/latest.json بوابة أداء الإصدار الاختياري (ARXI_SIDECAR_PERF_GATE=1) لفرض ترقية SLO، بما في ذلك توليد target/sidecar-perf/latest.json عبر مجموعة اختبارات أداء السايدكار.
system-test sidecar suites for end-to-end HTTP record/seal/build/verify and مجموعات اختبار النظام الجانبي لاختبار HTTP من النهاية إلى النهاية لتسجيل/إغلاق/بناء/تحقق واستمرارية إعادة التشغيل بشكل متكرر.
system-test Docker suite validating Dockerfile/Compose/config hardening plus Docker Compose build/up/down with containerized startup/readiness probes plus فتح/تسجيل/استعلام سير العمل.
system-test sidecar perf suite for write/read latency, throughput, memory مجموعة أداء نظام الاختبار الجانبي لاختبار زمن الكتابة/القراءة، وسرعة النقل، ونمو الذاكرة، وحقول تقرير التحميل الزائد-429 المستخدمة من قبل بوابة الأداء.

F:crates/arxi-sidecar-config/src/config/tests.rs F:crates/arxi-sidecar/tests/unit/middleware/bounds/tests.rs F:crates/arxi-sidecar/tests/unit/idempotency/tests.rs F:crates/arxi-sidecar/tests/error_registry_contract.rs F:crates/arxi-sidecar/tests/idempotency_restart.rs F:crates/arxi-sidecar/tests/http_contract_hardening.rs F:scripts/ci/sidecar_contract_gates.py F:scripts/ci/sidecar_perf_gate.py F:scripts/ci/generate_all.sh F:system-tests/tests/suites/sidecar.rs F:system-tests/tests/suites/sidecar_docker.rs F:system-tests/tests/suites/sidecar_perf.rs

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

المنطقة	الملف	الملاحظات
حدود الحاوية	`crates/arxi-sidecar/src/lib.rs`	نقاط دخول الحاوية العامة وتركيب الوحدات.
وقت التشغيل الثنائي	`crates/arxi-sidecar/src/main.rs`	سطر الأوامر، بدء الخدمة، وسلوك فحص الصحة.
التكوين + التحقق	`crates/arxi-sidecar-config/src/config.rs`, `crates/arxi-sidecar-config/src/validation.rs`, `crates/arxi-sidecar-config/src/schema.rs`, `crates/arxi-sidecar-config/src/compat.rs`	نموذج تكوين الحاوية القياسي، تحقق من الفشل عند بدء التشغيل، وآثار إسقاط التكوين الحتمية.
تمهيد الخادم	`crates/arxi-sidecar/src/server.rs`	توصيل التخزين/وقت التشغيل، بناء الموجه، دورة حياة النقل.
الحالة المشتركة	`crates/arxi-sidecar/src/state.rs`	مقبضات وقت التشغيل وبوابات التزامن.
سطح الخطأ	`crates/arxi-sidecar/src/error.rs`	نموذج خطأ API المنظم.
مستخلصات JSON	`crates/arxi-sidecar/src/extract.rs`	تطبيع صارم لحدود JSON لفشل التحليل المطبوع.
خط الأساس لعقد وقت التشغيل	`crates/arxi-sidecar/src/contract.rs`	إصدار API المصدّر وثوابت سجل الأخطاء المستخدمة في اختبارات العقد.
التكرارية	`crates/arxi-sidecar/src/idempotency.rs`	دلالات إعادة التشغيل/الصراع المستمرة وهاش الطلب القياسي.
بوابة سياسة المؤسسة	`crates/arxi-sidecar/src/control_plane_bridge.rs`	محول حدود المؤسسة فقط: فحوصات دخول خطة التحكم وإصدار عميل خطاف الحاوية.
وسيط المصادقة	`crates/arxi-sidecar/src/middleware/auth.rs`	فحوصات رمز الحامل مع مقارنة زمن ثابت.
وسيط المؤسسة	`crates/arxi-sidecar/src/middleware/enterprise.rs`	استخراج هوية المؤسسة وإنفاذ الحدود/تسلسل الخطاف.
وسيط الحدود	`crates/arxi-sidecar/src/middleware/bounds.rs`	تحكمات الرأس/المحتوى/الطابور/التزامن/مهلة.
تعبئة Docker	`docker/sidecar/Dockerfile`, `docker/sidecar/docker-compose.yml`, `docker/sidecar/config/sidecar.toml`, `docker/sidecar/README.md`	ملف تعريف بناء/وقت تشغيل الحاوية من الطرف الأول ودليل استخدام المشغل.
وحدات اختبار وحدة الحاوية	`crates/arxi-sidecar-config/src/config/tests.rs`, `crates/arxi-sidecar/tests/unit/idempotency/tests.rs`, `crates/arxi-sidecar/tests/unit/middleware/bounds/tests.rs`	تم إخراج اختبارات الوحدة من ملفات المصدر الإنتاجية لتنظيم الملفات بشكل أنظف.
اختبارات نظام Docker للحاوية	`system-tests/tests/suites/sidecar_docker.rs`	تعزيز Dockerfile/Compose والتحقق من سير العمل للحاوية المعبأة.
معالجات الاستطلاع	`crates/arxi-sidecar/src/handlers/health.rs`	سلوك الحضور/بدء التشغيل/الجاهزية، بما في ذلك أوضاع التشبع وجاهزية الاعتماد المؤسسي.
اختبارات توافق العقد	`crates/arxi-sidecar/tests/error_registry_contract.rs`, `crates/arxi-sidecar/tests/idempotency_restart.rs`, `crates/arxi-sidecar/tests/http_contract_hardening.rs`	فحوصات السجل، التكرارية عند إعادة التشغيل، وتعزيز حدود HTTP.
بوابات CI للعقد	`scripts/ci/sidecar_contract_gates.py`, `scripts/ci/sidecar_perf_gate.py`, `scripts/ci/generate_all.sh`	توافق إضافي فقط بالإضافة إلى تنسيق بوابة الأداء الاختياري للإصدار.
اختبارات نظام الحاوية	`system-tests/tests/suites/sidecar.rs`, `system-tests/tests/suites/sidecar_perf.rs`	تغطية دورة حياة HTTP من النهاية إلى النهاية وتوليد تقارير الأداء لبوابة SLO.
توافق الأمان	Docs/security/threat_model.md	رسم الخرائط للتهديدات بشكل موثوق والمخاطر المتبقية.