نظرة عامة على الحماية

ما هو السجل

تم تقطير كل فئة متكررة من الأخطاء في سجل FlareWatch إلى حماية مرقمة: قاعدة من فقرة واحدة، وتبرير، ومؤشر إلى المكان في الكود الذي ينفذها. يتم إضافة حماية جديدة عندما تظهر فئة من الأخطاء أو نمط يجب منعه من التكرار.

السجل عبارة عن وثيقة عمل، وليس نسخة تسويقية. الغرض منه هو الحفاظ على صدق الفريق — وحلقة المراجعة التي تأتي أولاً من التدقيق التي يستخدمها الفريق — فيما يتعلق بالقواعد التي تنطبق وأين. يتم الإشارة إلى السجل من تعليقات الأكواد المضمنة (على سبيل المثال، // Safeguard 24) بحيث يمكن لأي قارئ لأي ملف فردي أن يجد القاعدة التي تحكم الأسطر المحيطة.

هذه الصفحة هي الملخص العام. السجل الكامل يوجد في مستودع المصدر جنباً إلى جنب مع الكود الذي يحكمه. الغرض هنا هو إعطاء باحث الأمان، أو مراجع المنح، أو المساهم المتوقع، فهماً لفئات التي يغطيها السجل ونوع الانضباط الذي يفرضه.

لماذا سجل

سجل الحماية يستحق وجوده فقط إذا منع نفس الخطأ مرتين. سجل الإنجازات هو الإجابة:

• كل حماية تسمي الخطأ الذي تمنعه. القاعدة التي لا تملك حادثة مدروسة خلفها ليست حماية، بل هي تفضيل أسلوب. تفضيلات الأسلوب تنتمي إلى قواعد lint، وليس إلى السجل.
• يتم الإشارة إلى الحماية من الكود، وليس فقط من المستندات. تغيير الكود الذي ينتهك حماية يُقرأ كعلم في وقت المراجعة لأن رقم الحماية موجود في التعليقات المحيطة.
• يتم فرض بعض الحماية تلقائياً. يتم فرض مجموعة فرعية من خلال قواعد ESLint أو نصوص shell التي تعمل في CI. والباقي يعتمد على انضباط المؤلف بالإضافة إلى نمط المراجعة التي تأتي أولاً من التدقيق، والذي أثبت فعاليته في الممارسة.
• السجل يُحفظ صادقاً من خلال الاختبارات. يتم تثبيت العديد من الحمايات بواسطة اختبارات الانحدار التي تقرأ ملفات المصدر كنصوص وتؤكد أن الأنماط المعادية لا تظهر. الهشاشة هي الميزة: عملية إعادة هيكلة مستقبلية تعود إلى نمط معاد تفشل الاختبار قبل أن ينتقل الانحدار إلى الإنتاج.

الفئات

يتم تنظيم السجل حسب المجال. الفئات أدناه مستقرة؛ يتم إضافة حمايات محددة داخل كل منها مع اكتشاف أوضاع الفشل الجديدة.

عدد قليل من القواعد التمثيلية

هذه ملخصات آمنة للعامة لتدابير الحماية توضح طابع السجل. تم إعادة صياغتها وتقصيرها؛ النص الأساسي موجود بجانب الكود.

مصدر حقيقة واحد لقراءات البلوكتشين

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

نقطة اختناق واحدة للتحقق من الجلسة

كل مسار مصرح به في FlareWatch يتحقق من ملفات تعريف الارتباط للجلسة من خلال مساعد واحد. لا يتحقق أي معالج مسار من رموز الجلسة بشكل مستقل. هذا الثابت هو ما يجعل الإلغاء من جانب الخادم عالميًا — لا توجد أبواب جانبية تتجاوز الفحص.

حماية ملكية المحفظة من الطرفين

تتحقق المسارات الخاصة بكل محفظة من الملكية على جانب الخادم وليس جانب العميل. أنشأت عملية التدقيق الأصلية هذه القاعدة لأن الأعمال السابقة أغلقت بوابات جانب العميل لكنها تركت نقاط نهاية جانب الخادم مفتوحة تماماً. يتم الآن تتبع النصفين كمسلمات واضحة منفصلة — مغلقة على جانب العميل ومغلقة على جانب الخادم — لمنع هذا نمط الفشل من التكرار.

استخدام محددات مركزية وليس مضمنة

يتم تمرير جميع عمليات تنسيق الأرقام والعملات والتواريخ عبر مجموعة صغيرة من المساعدات المركزية. لا يقوم أي مكون بالتنسيق مضمناً. القاعدة لا علاقة لها بالأسلوب: عندما يتغير تعريف اللغة أو العملة الواحدة، يتحدث كل سطح في التطبيق معه. الانجراف بين الأسطح صامت وصعب الاكتشاف إلى أن يلاحظه المستخدم.

تحويلات الوحدات موثقة في الطرفين

عندما يتبادل جزآن من النظام قيماً قد تكون وحدتها غامضة (الثواني مقابل الميلي ثانية، عشري مقابل نسبة مئوية، عناوين بأحرف صغيرة مقابل عناوين مدققة)، يتم توثيق الاتفاقية في كل من المنتج والمستهلك. التعليق على طرف واحد فقط يتدهور؛ فقط عقد حد يتم التأكيد عليه على كلا الطرفين يبقى على قيد الحياة بعد إعادة الهيكلة.

تطبيق واحد لكل إجراء من قبل المستخدم

كل إجراء يبدأه المستخدم — إضافة محفظة مراقبة، تغيير معدل الضريبة، رفض تنبيه، تسجيل الخروج — له تطبيق واحد بالضبط. توجد القاعدة لأن الإجراءات التي تم تشغيلها من أجزاء مختلفة من واجهة المستخدم اعتادت على الانجراف بطرق دقيقة: نقطة دخول واحدة كانت تمسح ذاكرة تخزين مؤقت، بينما لا تفعل أخرى، وستحدث فئة من أخطاء "القيمة القديمة بعد العملية X".

أنماط الفشل التي يجب أن تكون صريحة

بعض أنماط الفشل صامتة بطبيعتها — مكافأة مصنفة بشكل خاطئ، عدم تطابق الوحدة الذي يحول إشعاراً إلى عدم عملية، سجل فصل لا يصل أبداً إلى متجر القيمة الرئيسية. حيثما أمكن، يشترط السجل أن يعلن منتجو هذه القيم عن عقدهم بصوت عالٍ بما يكفي لكي يفشل أي تغيير مستقبلي ينتهكه بصخب في الاختبارات قبل الوصول إلى الإنتاج.

كيف يتطور السجل

• حماية جديدة. تُضاف عندما تتكرر فئة من الأخطاء أو عندما يكلف خطأ واحد ما يكفي لتبرير قاعدة دائمة.
• حماية تم استبدالها. يتم الاحتفاظ بها في السجل مع علامة "تم استبدالها" ومؤشر إلى البديل، بحيث تبقى المراجع التاريخية في الكود قابلة للتفسير.
• تمت ترقيتها من ملاحظات العمل. تبدأ بعض الحماية كقواعد غير رسمية في وثيقة تسليم الجلسة وتتم ترقيتها إلى السجل بمجرد أن تثبت وزنها.
• الفحص ربع السنوي. يتم التحقق من استثناءات lint المؤقتة وعلامات "المراد إنجازه بحلول الربع القادم" على أساس ربع سنوي. يتم حل أي شيء قد انقضى وقته أو يتم تمديده بشكل صريح.

لماذا تم نشر هذا

تنشر FlareWatch هذه النظرة العامة، بدلاً من السجل الداخلي الكامل، لسببين.

• يحتوي السجل الداخلي على تفاصيل على مستوى الكود (مسارات الملفات، أسماء مخطط المفتاح والقيمة، طوابع زمنية للحوادث) مفيدة للفريق وللمراجع الأمني الذي لديه وصول إلى الكود، لكن لا يناسب نشرها دون هذا الوصول.
• الفئات والانضباط هما القصة الفعلية. يريد مراجع المنحة أو عالم الأمان الذي يقيّم FlareWatch أن يعرف نوع المشروع، مدى جديته بشأن الصحة، وكيف تبدو حلقة عمله — وليس ملف يحتوي على القاعدة رقم 91.

الباحثون الذين يرغبون في مناقشة ضمان معين، أو اقتراح ضمان جديد، أو الإبلاغ عن فجوة هم مرحب بهم للتواصل على [email protected].

قراءة إضافية

• العمارة — كيفية بناء FlareWatch.
• ميزات الأمان — المصادقة، التفويض، الرؤوس، سجل التدقيق.