وصل جزء من الرد وليس الحدث كله: ابن حدود SSE قبل قراءة بياناته
انتظر السطر الفارغ قبل إعلان وصول الحدث
يعيد test_split_inside_line إنتاج المشكلة بقيمتين نصيتين. نمرر أولاً data: he إلى EventFrames.feed فتعود قائمة فارغة، ثم نمرر بقية hello مع نهايتي سطر، فتعود قائمة فيها حدث message ببيانات hello ومعرف فارغ. لم تكن القطعة الأولى حدثاً ناقص الحقول يجب عرضه فوراً؛ كانت جزءاً من سطر لم يكتمل بعد. هذا هو السؤال الذي يعالجه المثال: أين تنتهي وحدة البيانات التي يجوز تسليمها إلى المستهلك؟
لا تختبر هذه القيم اتصال شبكة أو خدمة توليد. إنها أجزاء أدخلناها محلياً بترتيب معروف حتى نقرأ سلوك المؤطر. وفي تكامل شبكي مقترح قد تصل القطع بأحجام مختلفة، لكن حجم القطعة الذي تقرأه من النقل ليس عقد حدود الحدث. لذلك لا تضع كل قطعة مباشرة في محلل JSON أو تعرضها كرسالة مستقلة. حدد أولاً صيغة التدفق التي تتعامل معها، ثم استعمل الطبقة التي تجمع وحداته وفق المعنى الذي بنيت له.
قد تعيد feed قائمة بلا أحداث مع أنها احتفظت بمعلومات مفيدة، مثل أحرف من سطر أو سطر data كامل ينتظر الفاصل. لا تعني القائمة الفارغة أن البرنامج أضاع المدخل أو أن الخدمة لم تجب. إنها تصف ما اكتمل من أحداث في ذلك الاستدعاء فقط. وفي الاتجاه الآخر قد يكتمل أكثر من حدث خلال قطعة واحدة، فتكون القائمة ذات عدة عناصر. يجب أن يكون المستهلك قادراً على التعامل مع الحالتين دون مساواة عدد الاستدعاءات بعدد الرسائل.
تظهر الصورة الرئيسية آلة كاتبة فيروزية وورقة فارغة وصينيتان تحملان قصاصات على مكتب. تساعد فكرة تجميع القصاصات على شرح المشكلة، لكنها ليست التقاطاً لدفق حقيقي أو شاشة مراقبة موفر. المخرجات الفعلية موجودة في الاختبارات وactual-events.json. نحتفظ بطلب الصورة وأداتها وبصمتها في السجل، بينما نصف المشهد نفسه في التعليق والوصف البديل. لا نستعمل الصورة لإثبات زمن وصول أو اكتمال حدث لم يمر في شبكة.
اقرأ حالة المحلل بدلاً من جمع النص كله عشوائياً
يفصل السطر الفارغ أحداث SSE، وتجمع أسطر data بأسطر جديدة؛ التعليق يبدأ بنقطتين. يتجاهل التدفق كتلة أخيرة غير مكتملة عند نهايته. WHATWG HTML Standard server-sent events
تحتفظ EventFrames بحقل line للأحرف التي لم تكمل سطراً بعد، وبقائمة data لأسطر الحمولة التي تخص الحدث الحالي. يوجد أيضاً event لنوع الحدث، وident للمعرف الحالي، وskip_lf للتعامل مع نهاية CRLF، وfirst لفحص المحرف الأول، وclosed لمنع تغذية محلل أغلق. هذه حالات مختلفة ذات أعمار مختلفة. لو جمعت كل النص في متغير واحد ثم حذفت منه ما يبدو زائداً، فقد تفقد الفرق بين جزء سطر وبين حمولة تنتظر السطر الفارغ.
تطلب feed نصاً من نوع str. لا تحاول فك بايتات بداخله، ويغطي اختبارنا الإضافي رفض bytes مباشرة بـ TypeError. لذلك لا تعتبر ظهور أجزاء حرف عربي مشكلة سيصلحها مؤطر الأسطر تلقائياً إذا سلمته بايتات في طبقة غير مناسبة. نضيف لاحقاً موصلاً منفصلاً لفك UTF-8 ثم نسلم النص الناتج إليه. يظل كل حد واضحاً: فك الترميز ينتج محارف، والتأطير يستعمل تلك المحارف لبناء أسطر وأحداث.
عندما يصل محرف عادي، يضاف إلى line. وعند نهاية سطر يستدعي التنفيذ _line لقراءة الحقل، ثم يبدأ سطراً جديداً. إذا كان السطر فارغاً، يفحص هل توجد أسطر data، ويرسل الحدث عند وجودها ثم يفرغ قائمة البيانات ويعيد نوع الحدث إلى حالته الابتدائية. لا يمسح ident بالطريقة نفسها. يعكس ذلك اختلاف ما نريده من عمر معرف الحدث عن عمر بيانات الحدث الحالي في هذا التنفيذ، كما تثبت حالة استمرار المعرف.
للقارئ الذي يراجع الشيفرة، يفيد تتبع قيمة كل حقل عند نهاية كل سطر بدلاً من طباعة الدفق كله بعد فشل بعيد. اختر المدخل القصير hello واحسب متى تتغير line ومتى تنتقل القيمة إلى data ومتى تصبح عنصراً في قائمة الناتج. هذا أسلوب قراءة للمثال الأصلي، لا قياس أداء أو مدقق مطابق لكل تفاصيل المعيار. لا توجد في الفئة شبكة أو سياسة إعادة اتصال أو حدود حجم تخبرها كيف تدير تدفقاً غير منتهٍ.
event_frames.py
class EventFrames:
def __init__(self):
self.line='';self.data=[];self.event='';self.ident='';self.skip_lf=False;self.first=True;self.closed=False
def _line(self,out):
line=self.line;self.line=''
if line=='':
if self.data:out.append({'event':self.event or 'message','data':'\n'.join(self.data),'id':self.ident})
self.data=[];self.event='';return
if line.startswith(':'):return
field,sep,value=line.partition(':')
if value.startswith(' '):value=value[1:]
if field=='data':self.data.append(value)
elif field=='event':self.event=value
elif field=='id' and '\x00' not in value:self.ident=value
def feed(self,text):
if self.closed:raise ValueError('Parser closed')
if not isinstance(text,str):raise TypeError('Supply already-decoded text')
out=[]
for char in text:
if self.first:
self.first=False
if char=='\ufeff':continue
if self.skip_lf:
self.skip_lf=False
if char=='\n':continue
if char=='\r':self._line(out);self.skip_lf=True
elif char=='\n':self._line(out)
else:self.line+=char
return out
def finish(self):
self.closed=True;self.line='';self.data=[];self.event=''
return []
اجتازت الفئة النصية 12 طريقة محلية على Python 3.12.3 في Windows. يختبر الموصل البايتي 5 طرق إضافية مستقلة. النطاق هو حدود أسطر وأحداث اصطناعية؛ لا عميل HTTP أو متصفح أو إعادة اتصال أو اختبار موارد.
أسطر data والنوع والمعرف ليست النص نفسه
يفحص test_multiple_data_lines مدخلاً فيه data: a ثم data: b ثم السطر الفارغ. تكون بيانات الحدث a ثم محرف سطر جديد ثم b. في هذا المثال لا يرسل كل سطر data حدثاً مستقلاً؛ تحفظ الأسطر في قائمة وتجمع بواسطة join عند اكتمال الحدث. ولذلك قد تحتوي data النهائية أسطراً متعددة حتى لو كانت حدود الأحداث تعتمد على السطر الفارغ. لا تستبدل هذه العملية بضم بلا فاصل إذا كان مستهلكك يحتاج النص الأصلي بهذه البنية.
تختلف قائمة data الفارغة عن قائمة تحتوي سلسلة فارغة. عند السطر data: يضيف التنفيذ سلسلة فارغة إلى القائمة، فيصبح لديها عنصر. ومع السطر الفارغ التالي يرسل حدثاً بياناته فارغة، كما يفحص test_empty_data_event. أما استعمال شرط يعتمد على صدق النص المضموم فقد يسقط هذا الحدث. هذا مثال محدد على سبب اختيار البنية، لا دعوة لحذف الأحداث الفارغة في الواجهة أو افتراض أنها أخطاء شبكة؛ معنى الحمولة يقرره المستهلك بعد اكتمالها.
في test_custom_event_and_id يستقبل المحلل id: 7 وevent: done وdata: x قبل الفاصل. النتيجة حدث نوعه done وبياناته x ومعرفه النصي 7. إذا لم يحدد النوع، يستعمل التنفيذ message كما في حالة hello. لا يحول id إلى عدد صحيح ولا يفسر done بوصفه أمراً ينفذه. الحقول في الناتج تصف الحدث لكي يقرر المستهلك كيف يتعامل معه، ولا تتضمن تلقائياً نجاح مهمة أو نهاية رد من موفر لم نتصل به.
يختبر test_id_persists حدثاً أول يضع المعرف 7 ثم حدثاً لاحقاً بلا سطر معرف جديد، فيحتفظ الثاني به. وفي test_nul_id_ignored يدخل محرف NUL ضمن قيمة id فيتجاهل السطر، وتبقى قيمة المعرف الحالية فارغة في تلك الحالة. نذكر المدخل الفعلي بدلاً من دمج الحالتين في ادعاء اختبار لم يكتب. ويمكن قراءة شرط NUL في الشيفرة لمعرفة سبب التجاهل، لكن المجموعة لا تغطي كل تعاقب ممكن للمعرفات أو آلية استئناف خدمة.
يتجاهل التنفيذ حقولاً لا يعالجها، ومنها retry؛ لم نبن سياسة إعادة اتصال. لا يعني ذلك أن كل عميل SSE يمكنه تجاهل هذه الوظيفة حين يحتاج إليها. دور الفئة هنا تأطير مجموعة محددة من الحقول، لا استبدال EventSource بكل سلوكه. عند التكامل المقترح، حدد من يملك إعادة الاتصال وما الذي سيحفظه عن المعرف، ثم اختبر تلك الطبقة بمصدر فعلي. لا تنسبها إلى وجود حقل ident في قاموس النتيجة وحده.
نهايات الأسطر والمسافة الواحدة تغير حدوداً صغيرة
يتعامل feed مع LF ومع CR، ويستعمل skip_lf كي لا يحسب LF التابعة لـ CR كأنها سطر جديد إضافي. في test_crlf_split تنتهي القطعة الأولى بـ CR بعد data: a، ثم تأتي LF في قطعة لاحقة مع بقية الفاصل. لا ينتج الحدث مرتين بسبب تقسيم CRLF بين الاستدعاءين. تفحص الحالة عدد الأحداث الناتجة بعد اكتمال الحد، وهي مثال على أن حالة صغيرة يجب أن تبقى محفوظة بين القطع لا أن يعاد إنشاؤها عند كل قراءة.
أما test_lone_cr فيستعمل CR منفردة مرتين للفصل بين سطر data والسطر الفارغ، ويتوقع حدثاً واحداً. لا نطبع هذه المحارف بصرياً ونخمن عدد الأسطر؛ تظهر في المصدر كسلاسل هروب يمكن فحصها. وتظل LF حالة ظاهرة في بقية الاختبارات. هذه حالات محددة، وليست فحصاً لكل سلسلة محارف أو توزيع قطع ممكن. إذا غيرت معالجة النهايات، احتفظ بالمدخل الذي يقسم CRLF كي لا تتحول عودة ناجحة في حالة بسيطة إلى ثقة تتجاوزها.
عند قراءة سطر غير فارغ، يستعمل _line أول نقطتين لفصل الاسم عن القيمة، ثم يحذف مسافة عادية واحدة إن كانت أول القيمة. في test_one_optional_space_only يحتوي المدخل مسافتين بعد النقطتين، فتظل واحدة في بيانات الحدث. لذلك لا تستعمل strip على القيمة كلها إذا كنت تريد الحفاظ على هذه النتيجة. حذف الفراغات الطرفية قد يغير بيانات المستخدم، ويختلف عن إزالة المسافة الاختيارية التي يفحصها هذا الجزء من المحلل.
يتجاهل test_comments_ignored سطراً يبدأ بنقطتين مثل ping فينتج لا أحداث. ويفحص test_initial_bom محرف BOM في بداية النص قبل data، فيتجاوزه المحلل ثم يقرأ الحمولة x. تفحص first المحرف الأول الفعلي الذي تمرره الحلقة، ولا تمسح كل ظهور مشابه داخل المحتوى. ليست هذه معالجة عامة للنصوص أو تصحيحاً لترميز ملف؛ هي قاعدة صغيرة في قراءة البداية. احتفظ بالفصل بين قواعد الحقول وبين قرار فك الترميز الذي سنضعه في الموصل المحلي.
فك أجزاء UTF-8 أولاً في موصل محلي مستقل
ينشئ parse_byte_chunks مفكك UTF-8 تزايدياً بوضع strict، ثم ينشئ EventFrames ويجمع النتائج في قائمة. لكل قطعة bytes يستعمل decoder.decode مع final=False، ويسلم النص الناتج إلى feed. في النهاية يفرغ مفكك الترميز باستدعاء final=True، ويمرر أي نص متبقٍ قبل استدعاء finish. هذه هي شيفرة local_byte_stream.py المرفقة. إنها موصل محلي لقائمة قطع اصطناعية، وليست طلب HTTP أو مولداً يعيد أحداث شبكة إلى واجهة أثناء الانتظار.
تظهر فائدة المفكك التزايدي عندما تنتهي قطعة داخل بايتات حرف عربي. يحتفظ مفكك الترميز بالجزء الذي يحتاج تكملة، ثم ينتج المحرف بعد وصول بقيته. لا يحتاج EventFrames إلى معرفة أين انقسمت بايتات ذلك الحرف؛ يتلقى str بعد فكها. والاحتفاظ بحالة السطر داخل المؤطر يعالج مستوى آخر من التقسيم. يمكن أن يكون الحرف كاملاً لكن السطر ناقصاً، أو السطر كاملاً والحدث ينتظر الفاصل. نجاح مستوى لا يعني اكتمال الوحدات في المستوى الآخر.
استعملنا حدثاً نصه data: ثم مسافة ومرحبا ثم LF مرتين، وحفظنا المخرج العربي الفعلي. يتكون دفق UTF-8 لهذه الحالة من 18 بايتاً، وله 19 موضعاً لقطع واحد إذا حسبت الطرفين. يمر test_each_single_cut_of_arabic_event على كل موضع ويعطي الموصل قطعتين ثم يقارن الناتج المتوقع. هذا لا يختبر جميع توزيعات الدفق إلى ثلاث قطع أو أكثر ولا كل حرف عربي. إنه فحص شامل لمواضع قطع مفرد في ذلك المدخل المحدد.
في test_truncated_utf8_rejected_on_final_flush ننهي المدخل ببايت قيمته 216 يحتاج تكملة، فيثير تفريغ المفكك UnicodeDecodeError. يختلف ذلك عن نص صحيح الترميز لكنه لم يكمل حدثاً، والذي يختبره مسار آخر. لا تبتلع الخطأ وتعرض البايت الناقص على أنه رد فارغ صالح. وفي المقابل لا تصف إسقاط حدث بلا فاصل كأنه فشل UTF-8 إذا كانت المحارف نفسها صحيحة. نوع الطبقة التي رفضت المدخل يساعد في تفسير نتيجة التنفيذ.
يجمع هذا الموصل الأحداث ثم يعيد القائمة بعد اكتمال القطع والتفريغ. لا توجد فيه آلية تسليم تدريجي للمستهلك أو استعادة نتائج عند خطأ لاحق. إذا أردت في تطبيق لاحق yield أو callback، فحدد متى تسلم الحدث وماذا يحدث عند فشل فك قطعة لاحقة. هذا تغيير في واجهة الموصل يحتاج اختباراً جديداً. لا تنسب إلى الدالة الحالية استجابة فورية أو زمناً قصيراً لم نقسه، لمجرد أن اسمها يتضمن أجزاء بايت.
تفحص test_two_events_keep_order قيمتي A وB في حدثين منفصلين، وتتوقع بقاء الترتيب نفسه في النتائج. وتفحص test_text_parser_itself_rejects_bytes حد النوع في EventFrames مباشرة. تتكامل الحالتان مع الموصل دون أن تلغيا عقد الفئة الأصلية؛ لم نغير feed لتقبل البايتات أحياناً والنص أحياناً. بقاء هذا الحد واضحاً يجعل مراجعة الكود أبسط: مفكك الترميز مسؤول عن النص، والمؤطر مسؤول عن الأسطر والأحداث، والمستهلك مسؤول عن معنى البيانات.
local_byte_stream.py
import codecs
from event_frames import EventFrames
def parse_byte_chunks(chunks):
decoder=codecs.getincrementaldecoder('utf-8')('strict')
parser=EventFrames()
events=[]
for chunk in chunks:
events.extend(parser.feed(decoder.decode(chunk,final=False)))
events.extend(parser.feed(decoder.decode(b'',final=True)))
events.extend(parser.finish())
return events
اجتاز الموصل المحلي 5 طرق، منها 19 موضع قطع مفرد لحالة عربية واحدة طولها 18 بايتاً. ليست الحالات الفرعية طرقاً إضافية. حفظ الحدث العربي الناتج في actual-events.json. لم يقرأ دفق شبكة أو يشغّل موفراً أو يقس زمناً.
انتهاء الدفق ليس سطراً فارغاً إضافياً
في test_eof_does_not_dispatch نمرر data:x مع نهاية سطر واحدة، ثم نستدعي finish. لا تعيد feed حدثاً، ولا تعيد finish حدثاً. احتاجت الكتلة إلى السطر الفارغ الذي لم يصل؛ نهاية المدخل ليست إذناً بإرساله بدلاً منه. يحتفظ هذا الاختبار بقرار واضح عند الحد، ولا يملأ محارف مفقودة لكي يبدو الرد مكتملاً. قد يحتاج التطبيق إلى إبلاغ المستخدم بانقطاع النقل، لكن رسالة ذلك التطبيق ليست جزءاً من الناتج الذي تبنيه هذه الفئة.
يفحص test_unterminated_event_is_not_dispatched الحالة من جهة الموصل البايتي: يمرر data: one مع LF واحدة، ثم ينتهي تسلسل القطع، فتعود قائمة فارغة. بذلك لا يضيف الموصل فاصل حدث أثناء تفريغ مفكك الترميز. تفريغ UTF-8 يختبر هل بقيت بايتات غير مكتملة؛ لا يملك تغيير دلالة نهايات الأسطر. تعالج الحالتان حدوداً متتابعة في التنفيذ، مع الاحتفاظ بالفرق بين نص ناقص الحد ونص لا يمكن فك بايتاته.
تضع finish الفئة في حالة closed وتفرغ ما بقي من السطر والبيانات والنوع في هذا المثال. وفي المصدر، محاولة feed بعد الإغلاق تثير ValueError. هذه قراءة للحارس، وليست ادعاء إضافة طريقة اختبار لكل تسلسل ممكن بعد الإغلاق. إذا احتاج مشروعك إلى إعادة استعمال محلل لطلب جديد، أنشئ حالة جديدة وفق عقده بدلاً من تمرير دفق آخر إلى كائن مغلق مع توقع أنه سينسى الاتصال السابق تلقائياً.
لا توجد حدود قصوى لطول line أو عدد أسطر data أو حجم القائمة التي يجمعها الموصل. لذلك لا نحول اختبارات القطع الصغيرة إلى ضمان موارد لخدمة تتلقى نصاً بلا نهاية. يمكن لتكامل مقترح وضع حد للحجم وسياسة إلغاء وتسجيل للانقطاع، ثم اختبارها حيث تنفذ فعلاً. لم نقس سرعة أو ذاكرة، ولا ننسب تعقيداً زمنياً مقاساً إلى هذه الشيفرة. ما نملكه هو أثر المدخلات المحددة على الحالة والناتج.
احتفظ ببايتات المثال إلى جانب الحدث الناتج
حفظنا أيضاً synthetic-stream.bin، وهو تسلسل البايتات الثمانية عشر للمدخل العربي الاصطناعي، وليس تسجيلاً لاستجابة من خدمة. يحتفظ partition-at-7.json ببصمة هذا التسلسل وموضع قطع مقداره 7 بايتات وطولي القطعتين 7 و11 والحدث الناتج. يوضح هذا الموضع حالة انقسام داخل الحرف الأول من الكلمة العربية بعد بادئة data والمسافة. مررنا القطعتين إلى الموصل فعلياً وتحققنا من النتيجة؛ وهو توضيح محفوظ لحالة تقع أصلاً داخل حلقة المواضع التسعة عشر، فلا نضيفه كطريقة unittest جديدة.
الاحتفاظ بالمدخل والنتيجة يعطي القارئ وسيلتين مختلفتين للفحص. ملف البايتات يحدد ما قرأه مفكك UTF-8، وقاموس الحدث يحدد ما سلّمه المؤطر بعد تفسير الأسطر. لا يستطيع JSON الناتج وحده أن يخبرك بأي موضع انقسم النقل، ولا تعني رؤية الكلمة كاملة فيه أن كل قطعة بايت كانت قابلة للفك منفردة. عند تكرار هذه الحالة، اقرأ الملف كـ bytes ثم قسمه في الموضع المحفوظ قبل تمريره إلى الموصل، بدلاً من إعادة ترميز نصف سلسلة محارف وقول إنك اختبرت انقسام الحرف.
لا توجد ترويسات HTTP أو أزمنة وصول أو معرفات طلب حقيقية في هذا السجل. أضف تلك البيانات فقط عندما تشغّل تجربة نقل تحتاجها وتحدد ما يسمح بحفظه. بصمة المدخل تربط المثال بالبايتات التي شغلتها، لكنها ليست اعتماداً بشرياً ولا شهادة مطابقة لكل SSE. ويمكن إبقاء الحدث العربي القصير حالة عامة قابلة للمشاركة عندما لا تريد نسخ حمولة مستخدم فعلية إلى تقرير. يبقى كل وصف للسجل مرتبطاً بالطبقة التي صنعته وبالحد الذي تستطيع استعادته منه.
سلّم الحدث إلى مستهلك يعرف عقد الحمولة
بعد اكتمال الحدث، يملك المستهلك قاموساً فيه event وdata وid. ليس مطلوباً من المؤطر أن يحول data إلى JSON؛ قد تكون نصاً عادياً، كما في hello ومرحبا. في تكامل مقترح افحص نوع الحدث وعقد الخدمة ثم اختر محلل الحمولة المناسب. إذا كانت خدمة محددة توثق JSON داخل data، فسيكون رفض JSON غير صالح قراراً في تلك الطبقة. لم نتصل هنا بموفر ولم نفحص مخطط بياناته أو رسائل اكتماله.
يختلف ذلك عن قراءة JSONL سطراً بسطر في المقال العربي المرتبط. قد تضم data عدة أسطر تخص حدثاً واحداً، بينما يبدأ JSONL من عقد سجل مستقل لكل سطر. اختيار المؤطر لا يعتمد على أن النص جاء من رد ذكاء اصطناعي أو أن الحقل اسمه data؛ يعتمد على الصيغة التي ينتجها المصدر. لا تستعمل محلل JSONL ثم تحاول ترقيعه بإزالة بادئة data إذا كان المطلوب SSE، لأن الاختبارات هنا تبين أن حدود الأسطر وحدها لا تساوي حدود الأحداث.
يمكن لمستهلك مقترح معالجة كل عنصر من القائمة العائدة بترتيبه، مع التمييز بين عدم اكتمال حدث وبين حدث بياناته فارغة. إذا قفزت فوق كل سلسلة فارغة دون النظر إلى النوع، فقد تتجاهل قيمة مسموحة في عقد المستهلك. وإذا عرضت القائمة الفارغة على أنها فشل طلب، فقد تعلن خطأ قبل أن يصل الفاصل. هذه قرارات واجهة يجب اختبارها عندما تبنى، ولا نختلق تجربة شاشة لإثباتها من نجاح مؤطر نصوص محلي.
قد يرغب التطبيق في حفظ المعرف للاستئناف أو التعامل مع أنواع خاصة، لكن وجود ident في الناتج لا ينشئ آلية إعادة اتصال. لم ينفذ المثال ترويسة Last-Event-ID أو retry أو بروتوكول استئناف لمهمة توليد. عند إضافة تلك الطبقة، احتفظ بالتمييز بين المعرف الذي لاحظه المؤطر والسلوك الذي وعدت به الخدمة الفعلية. يمكن أن تساعد هذه الفئة في تجهيز حدث للمستهلك، لكن لا ينبغي عرضها كبديل كامل لعميل متصفح لم نكتبه أو نشغله.
إذا كانت البيانات التي يقرأها التطبيق حساسة، فليحدد ما يسجله من الحدث في طبقة تعرف معناها. لا يحتاج تشخيص حد سطر إلى نسخ محادثات أو مفاتيح اتصال داخل تقرير عام. يمكن بدء الاختبار بالمدخل القصير المحفوظ، ثم إضافة حالة منقحة تحافظ على الخاصية التي تريد فحصها. سجلاتنا تستعمل قيماً اصطناعية وأرقام معرفات بسيطة. هذا يتيح تكرار المشكلة دون الادعاء بأننا اختبرنا بيانات مستخدمين أو خدمة إنتاجية.
كرر الملفات الأربعة واقرأ ما أثبتته الطرق السبعة عشر
احفظ event_frames.py وlocal_byte_stream.py وtest_example.py وtest_bytes.py في مجلد واحد. المجموعة الأصلية تستورد المؤطر، والمجموعة الإضافية تستورد المؤطر والموصل. افحص الشيفرة قبل التشغيل؛ فهي لا تفتح شبكة أو خدمة خارجية، بل تقرأ السلاسل والبايتات التي تكتبها الاختبارات. شغلت الحالات محلياً على Python 3.12.3 في Windows، وحفظت النتائج وبصمات المصدر وملف actual-events.json الذي يحتوي الحدث العربي الناتج فعلاً.
لتكرار المجموعة الأصلية في نسختك، استعمل python -m unittest discover -s . -p test_example.py -v، ثم استعمل الأمر المقابل مع test_bytes.py للمجموعة الإضافية. السجل يحتفظ بمسار المفسر ومجلد الاكتشاف الحقيقيين المستخدمين محلياً؛ هذه صيغة مختصرة لإعادة التشغيل من مجلدك. لا تعتمد على ظهور كلمة نجاح وحدها إذا تغيرت الملفات. قارن اسم المجموعة وبصمة الشيفرة كي تعرف أن السلوك الذي تقرأه هو السلوك الذي شغله السجل.
تضم المجموعة الأولى 12 طريقة: تقسيم السطر، وتعدد data، وCRLF المقسومة، وCR المنفردة، والتعليق، والنوع والمعرف، واستمرار المعرف، وNUL في id، وdata الفارغة، والمسافة الواحدة، وBOM الأول، ونهاية الدفق. لكل واحدة مدخل محدد وassertion مقروء. لا تساوي هذه القائمة فحص كل تفاصيل WHATWG أو كل حالة نقل. المصدر الرسمي يدعم تعريف الصيغة الذي نستند إليه، بينما شيفرتنا ونتائجها تحدد نطاق ما نفذناه فعلاً.
تضيف المجموعة الثانية 5 طرق: جميع مواضع قطع واحد للحدث العربي، وترتيب حدثين، ورفض بايت UTF-8 ناقص عند التفريغ، وإسقاط حدث غير منتهٍ، ورفض bytes في الفئة النصية. المجموع 17 طريقة مختلفة. وتحتوي الطريقة العربية 19 حالة فرعية، وليست 19 طريقة إضافية. يحفظ ملف النتيجة عددها والحدث الناتج، كما فحصنا نقاط شيفرة مرحبا الفعلية عندما شوّه عرض الطرفية شكلها. النتيجة بيانات عربية صحيحة في الملف، لا علامات استفهام استنتجناها من المظهر.
قبل تحويل المثال إلى خدمة، اكتب ما ستضيفه: مصدر بايتات فعلي، وحدود حجم، وإلغاء، وتفسير أنواع وحمولات، وربما إعادة اتصال. سجل أي اختبار جديد باسم الطبقة التي شغّلها، واحفظ المخرجات عند وجودها. لا تنقل نجاح المثال المحلي إلى ادعاء توافر موفر أو زمن استجابة أو جودة فيديو. التسليم الحالي يعطيك وحدتين واضحتين وملفات تكرار وحدثاً محفوظاً، وهي نقطة بداية عملية لبناء التكامل دون خلط نجاحات لم تحدث مع النتائج الموجودة.
عند تعديل أحد الحدين، حافظ على الحالة التي تخصه. تغيير مفكك الترميز يحتاج مراجعة البايت الناقص والقطع داخل الحرف؛ وتغيير المؤطر يحتاج مراجعة السطر الفارغ وCRLF وdata الفارغة. لا تعالج خطأ حدود بإضافة محارف إلى نهاية كل رد حتى ينجح المثال، ولا تفسر كل قائمة فارغة كأنها لا تحمل حالة متراكمة. اتبع السطر والحدث اللذين يعرفهما عقدك، ثم اختبر المستهلك على ناتج مكتمل وفق ذلك العقد.
test_example.py
import unittest
from event_frames import EventFrames
class EventTests(unittest.TestCase):
def test_split_inside_line(self):
p=EventFrames();self.assertEqual(p.feed('data: he'),[]);self.assertEqual(p.feed('llo\n\n'),[{'event':'message','data':'hello','id':''}])
def test_multiple_data_lines(self):self.assertEqual(EventFrames().feed('data: a\ndata: b\n\n')[0]['data'],'a\nb')
def test_crlf_split(self):
p=EventFrames();self.assertEqual(p.feed('data: a\r'),[]);self.assertEqual(len(p.feed('\n\r\n')),1)
def test_lone_cr(self):self.assertEqual(len(EventFrames().feed('data:a\r\r')),1)
def test_comments_ignored(self):self.assertEqual(EventFrames().feed(':ping\n\n'),[])
def test_custom_event_and_id(self):self.assertEqual(EventFrames().feed('id: 7\nevent: done\ndata: x\n\n'),[{'event':'done','data':'x','id':'7'}])
def test_id_persists(self):
p=EventFrames();p.feed('id:7\ndata:a\n\n');self.assertEqual(p.feed('data:b\n\n')[0]['id'],'7')
def test_nul_id_ignored(self):self.assertEqual(EventFrames().feed('id:a\x00b\ndata:x\n\n')[0]['id'],'')
def test_empty_data_event(self):self.assertEqual(len(EventFrames().feed('data:\n\n')),1)
def test_one_optional_space_only(self):self.assertEqual(EventFrames().feed('data: x\n\n')[0]['data'],' x')
def test_initial_bom(self):self.assertEqual(EventFrames().feed('\ufeffdata:x\n\n')[0]['data'],'x')
def test_eof_does_not_dispatch(self):
p=EventFrames();self.assertEqual(p.feed('data:x\n'),[]);self.assertEqual(p.finish(),[])
test_bytes.py
import unittest
from event_frames import EventFrames
from local_byte_stream import parse_byte_chunks
class ByteIntegrationTests(unittest.TestCase):
def test_each_single_cut_of_arabic_event(self):
stream='data: مرحبا\n\n'.encode('utf8')
for cut in range(len(stream)+1):
with self.subTest(cut=cut):
self.assertEqual(parse_byte_chunks([stream[:cut],stream[cut:]]),[{'event':'message','data':'مرحبا','id':''}])
def test_two_events_keep_order(self):
self.assertEqual([x['data'] for x in parse_byte_chunks([b'data: A\n\n',b'data: B\n\n'])],['A','B'])
def test_truncated_utf8_rejected_on_final_flush(self):
with self.assertRaises(UnicodeDecodeError):parse_byte_chunks([b'data: '+bytes([216])])
def test_unterminated_event_is_not_dispatched(self):
self.assertEqual(parse_byte_chunks([b'data: one\n']),[])
def test_text_parser_itself_rejects_bytes(self):
with self.assertRaises(TypeError):EventFrames().feed(b'data: one\n\n')
أُعد المقال بمساعدة أدوات ذكاء اصطناعي ومراجعات آلية. شُغلت الشيفرة الأصلية محلياً ضمن نطاق الاختبارات المسجل. الصورة الرئيسية توضيحية، وليست تصويراً ميدانياً أو دليلاً على اختبار متصفح أو جدول بيانات أو فيديو.
التعليقات
كن أول من يعلّق على هذا المقال.