Chunked/Resumable Transfer

1. مسئله واقعی: ادامه انتقال با «اعتماد به فایل» یکی نیست

یک artifact مدل 12 GiB با digest مورد انتظار sha256:D1 و اندازه دقیق S1 را در نظر بگیرید. ارتباط در میانه انتقال قطع می‌شود و client آخرین ACK محلی خود را دقیق به خاطر ندارد. اگر فقط از روی offset محلی ادامه دهیم ممکن است بخشی از داده دوباره یا خارج از ترتیب ارسال شود؛ اگر فقط اندازه نهایی را چک کنیم نیز corruption می‌تواند پنهان بماند. artifact مالک این درس Resumable Artifact Transfer Session & Integrity Harness v1 است.

2. مرز درس: transport را کنترل می‌کنیم، نه topology یا license

AIE-014 هویت artifact را از AIE-013 مصرف می‌کند و فقط protocol انتقال قابل‌ازسرگیری را مالک است. موفقیت انتقال هیچ permission مجوزی ایجاد نمی‌کند؛ AIE-015 آن را بررسی می‌کند. انتخاب node به AIE-016 و سلامت GPU/Media runtime به AIE-017 تعلق دارد. پس outcome این درس محدود به «دریافت همان bytes مورد انتظار و publish امن آن‌ها» است.

3. session باید به digest و size مورد انتظار bind شود

در شروع session حداقل session_id، target_artifact_digest و expected_size را ثبت کنید. Friendly name یا filename کافی نیست. اگر artifact هدف عوض شد، session قبلی نباید برای artifact جدید reuse شود؛ حتی اگر نام فایل یکسان باشد. این binding جلوی resume شدن روی هویت اشتباه را می‌گیرد.

4. progress authority سمت server است

پس از interruption، client نباید آخرین offset محلی خود را حقیقت نهایی بداند. state قابل اتکا همان range/offsetی است که service انتقال به‌عنوان دریافت‌شده تأیید می‌کند. در الگوی chunked upload در OCI نیز پاسخ chunk موفق range دریافت‌شده را گزارش می‌کند و GET می‌تواند state معتبر فعلی upload را برگرداند. بنابراین resume_offset = server_ack_end + 1، نه «آخرین چیزی که client فکر می‌کند فرستاده است».

5. chunkها ordered هستند و gap/overlap باید رد شود

هر chunk بعدی باید دقیقاً از byte بعد از آخرین range تأییدشده شروع شود. chunkی که جلوتر می‌پرد، overlap ناموجه دارد یا ترتیب را می‌شکند نباید acknowledged state را جلو ببرد. در harness این وضعیت REJECT_CHUNK است و partial blob همچنان NON_RUNNABLE می‌ماند.

6. retry باید idempotent و محدود باشد

قطع ارتباط طبیعی است، اما retry کورکورانه خطر دارد. retry باید به همان session معتبر و همان identity متصل باشد، از state تأییدشده server شروع شود و شمارش/علت retry در audit ثبت شود. اگر session دیگر معتبر نیست یا identity آن با artifact هدف تطبیق ندارد، نتیجه RESTART_REQUIRED است؛ نه حدس زدن offset.

7. partial blob هرگز runnable replica نیست

اینکه 90٪ bytes رسیده‌اند یا همه chunkها ACK شده‌اند هنوز replica قابل اجرا نمی‌سازد. partial artifact باید state صریح مثل NON_RUNNABLE داشته باشد و از catalog اجرایی یا scheduler پنهان بماند. transport progress فقط نشان می‌دهد چه مقدار داده دریافت شده؛ integrity هنوز اثبات نشده است.

8. size check لازم است اما کافی نیست

OCI descriptor برای محتوای referenced یک digest و byte size دارد و مصرف‌کننده باید اندازه را پیش از اعتماد بررسی کند. در طراحی ما نیز final_size == expected_size یک gate سخت است. اما دو payload با اندازه برابر می‌توانند bytes متفاوت داشته باشند؛ بنابراین size match به‌تنهایی publish را مجاز نمی‌کند.

9. digest check هویت محتوای نهایی را می‌بندد

پس از کامل شدن candidate، digest کل bytes را دوباره محاسبه و با target_artifact_digest مقایسه کنید. اگر size درست ولی digest غلط باشد، artifact باید QUARANTINE شود. offsetها و ACKهای موفق تاریخی این failure را خنثی نمی‌کنند؛ آن‌ها transport evidence هستند، نه content identity.

10. publish باید atomic و پس از verify باشد

تا قبل از عبور هم‌زمان از size و digest verification، candidate در مسیر موقت می‌ماند. تنها پس از verify موفق، یک operation اتمیک آن را به replica قابل مشاهده تبدیل می‌کند و replica_id و audit event ثبت می‌شود. downstream نباید حالت میانی بین «verified» و «published» را به‌عنوان replica کامل ببیند.

11. quarantine یک failure تایپ‌شده است، نه فایل مبهم

برای mismatchها quarantine_reason را دقیق ثبت کنید: FINAL_DIGEST_MISMATCH، FINAL_SIZE_MISMATCH یا SESSION_IDENTITY_MISMATCH. Candidate quarantined نه حذف اجباری می‌شود و نه runnable؛ evidence آن برای diagnosis باقی می‌ماند. این state از تبدیل failure به success خاموش جلوگیری می‌کند.

12. audit trail باید قابل بازسازی باشد

رکورد انتقال باید session ID، digest/size هدف، chunk index و sent range، acknowledged range، resume offset، upload location، retry count، interruption reason، نتیجه out-of-order، final digest/size و publish/quarantine state را نگه دارد. هدف این است که reviewer بدون حدس بتواند بفهمد چرا resume یا publish انجام شده است.

13. الگوی OCI یک reference pattern است، نه الزام معماری MAKNOW

OCI Distribution Specification الگوی فعلی POST → PATCH → PUT برای chunked blob upload و retrieval state برای resume را مستند می‌کند. MAKNOW مجبور نیست registry OCI باشد؛ ما safety propertyها را می‌گیریم: session صریح، progress تأییدشده server، ترتیب chunk، closure مشخص و integrity verification نهایی. state machine دقیق harness یک design decision این پروژه است.

14. Lab: هشت fixture برای شکستن shortcutهای رایج

Case 1 نشان می‌دهد client ACK جلوتر از server است و resume باید از server-confirmed offset انجام شود. Case 2 chunk خارج از ترتیب را رد می‌کند. Case 3 با size درست و digest غلط به quarantine می‌رود. Case 4 size mismatch را می‌بندد. Case 5 تنها مسیر publish موفق را نشان می‌دهد. Case 6 session منقضی را restart می‌کند. Case 7 session با identity ناسازگار را reuse نمی‌کند. Case 8 در changed-context ثابت می‌کند session artifact قدیمی برای digest جدید قابل انتقال نیست.

15. Transfer و چک‌لیست نهایی

در transfer، یک chunk را تغییر دهید ولی تعداد byteها را ثابت نگه دارید. offset و size می‌توانند ظاهراً صحیح باشند، اما final digest باید mismatch را آشکار کند و candidate unpublished در quarantine بماند. چک‌لیست نهایی: identity دقیق؛ session binding؛ server-confirmed resume؛ ordered ranges؛ retry محدود؛ partial=NON_RUNNABLE؛ final size؛ final digest؛ atomic publish؛ quarantine reason؛ replica ID فقط پس از publish؛ audit event؛ و requalification وقتی identity/session semantics تغییر می‌کند.