در زمان آپلود فایل‌ها در بستر شبکه، مشکلاتی مانند اختلال، کندی و قطعی می‌توانند باعث از بین رفتن فرایند انجام‌شده شوند. این مشکل به‌خصوص در استفاده از APIها ممکن است مشکلاتی را برای توسعه‌دهندگان ایجاد کند. برای مثال، ممکن است از طریق API پلتفرم میزبانی ویدیو ابر آروان در حال بارگذاری یک فایل صوتی یا تصویری باشید و به‌دلیل قطعی لحظه‌ای اینترنت، ارتباط شما با سرورهای ابر آروان دچار مشکل شود. به این ترتیب و با نبود امکان ادامه‌ی فرایند آپلود، باید بارگذاری فایل را مجددن شروع کنید که تکرار این اتفاق، به هیچ وجه خوشایند نیست.
با هدف تسهیل آپلود فایل‌ها و فراهم آوردن امکان ادامه‌ی بارگذاری پس از قطعی، پروتکلی به‌نام TUS ایجاد شده است. با استفاده از این پروتکل متن‌باز، آپلود فایل‌ها در پلتفرم میزبانی ویدیو ابر آروان به‌شکل Resumable خواهد بود. منظور از آپلود فایل به‌شکل Resumable آن است که اگر ارتباط هنگام انجام هریک از مراحل آپلود به هر دلیلی قطع شود، این قابلیت وجود دارد که فرآیند، مجدد از بخش Fail شده ادامه پیدا کند.
پروتکل TUS بر پایه‌ی HTTPS/HTTP است و برای پلتفرم‌های مختلف مانند مرورگرها و اپلیکیشن‌های دسکتاپ و موبایل طراحی و توسعه داده شده است. نکته‌ی قابل توجه درباره‌ی این پروژه، استفاده از پروتکل اختصاصی در پیاده‌سازی Client و Server است.
در این راهنمای فنی شیوه‌ی استفاده از پروتکل TUS را خصوصن برای کار با API پلتفرم میزبانی ویدیو ابر آروان بررسی می‌کنیم. هم‌چنین، مستندات شیوه‌ی پیاده‌سازی این پروتکل را می‌توانید در وب‌سایت TUS بررسی کنید.
درخواست‌ها در TUS
برای مشخص کردن آن‌که Offset آپلود باید از کجا ادامه پیدا کند، از درخواست HEAD استفاده می‌شود. نمونه‌ی زیر نشان‌دهنده‌ی آن است که یک فایل ۱۰۰ بایتی تا کجا آپلود شده است. با درخواست PATCH می‌توان فرایند آپلود را از ادامه‌ی این بخش مجدد از سر گرفت.
درخواست
HEAD /files/24e533e02ec3bc40c387f1a0e460e216 HTTP/1.1 Host: tus.example.org Tus-Resumable: 1.0.0
پاسخ
HTTP/1.1 200 OK Upload-Offset: 70 Tus-Resumable: 1.0.0
با استفاده از Upload-Offset می‌توان ارسال فایل را از ادامه‌ی آن از سر گرفت. برای مثال:
PATCH /files/24e533e02ec3bc40c387f1a0e460e216 HTTP/1.1 Host: tus.example.org Content-Type: application/offset+octet-stream Content-Length: 30 Upload-Offset: 70 Tus-Resumable: 1.0.0 [remaining 30 bytes]
که با پاسخی مانند زیر مواجه خواهد شد.
HTTP/1.1 204 No Content Tus-Resumable: 1.0.0 Upload-Offset: 100
هدرهای پروتکل TUS
هدرها در پروتکل TUS از اهمیت بالایی برخوردار هستند. در بخش زیر با تعدادی از هدرهای اصلی این پروتکل آشنا می‌شوید.
- Upload-Offset: میزان بایت آپلود شده را نمایش می‌دهد (Offset) و باید یک عدد مثبت باشد.
- Upload-Length: حجم کلی فایل آپلودی (بایت) را نمایش می‌دهد و باید یک عدد مثبت باشد.
- Tus-Version: می‌توان آخرین Version، یا با استفاده از Comma، فهرست Versionهایی که به‌وسیله‌ی پروتکل پشتیبانی می‌شوند را وارد کرد. فهرست باید مطابق آخرین ورژن‌ها وارد شود. برای مثال:
Tus-Version: 1.0.0,0.2.2,0.2.1
- Tus-Resumable: توجه داشته باشید که این هدر باید در تمامی Request/Responseها به جز OPTIONS وجود داشته باشد و مقدار آن نیز باید برابر Version پروتکلی باشد که Server یا Client از آن استفاده می‌کنند. هم‌چنین، اگر Version پشتیبانی نشود خطای 412 Precondition Failed نمایش داده می‌شود. برای مثال:
Tus-Resumable: 1.0.0 Tus-Version: 1.0.0,0.2.2,0.2.1
- Tus-Max-Size: عددی مثبت و نشان‌دهنده‌ی محدودیت آپلود فایل به بایت است.
- Upload-Metadata: مقدار آن باید یک یا چند key-value باشد که با استفاده از Comma از هم جدا شده‌اند. مقدار Key و Value باید با Space از هم جدا شوند و مقدار Key باید به‌شکل ASCII Encoded و Value باید Base64 Encoded باشد. به‌عنوان مثال و برای فایلی به نام video.mp4:
Upload-metadata: filename dmlkZW8ubXA0,filetype dmlkZW8vbXA0
در این مثال، Valueهای بالا به‌دلیل این قرار داده شده‌اند که تبدیل مقدار base 64 فایل video.mp4 برابر است با dmlkZW8ubXA0 و تبدیل مقدار base 64 فایل video/mp4 برابر است با dmlkZW8vbXA0. برای بررسی موارد دیگر، می‌توانید از سایت‌هایی مشابه Base64encode استفاده کنید. در این مثال، پاسخ سرور برای ایجاد فایل، 201 خواهد بود و URL فایل در Response Header در قسمت Location قرار می‌گیرد.