سؤال مصاحبه

وب‌هوک‌هایی که ممکن است دوبار فراخوانی شوند یا اصلاً ارسال نشوند

A webhook that may fire twice or not at all

  • سطح ۳: ارشد
  • بده‌بستان
  • ۱۰ دقیقه

مدت اجرای یک تست از هر اتصالی که برنامه‌ریز (planner) شما بتواند باز نگه دارد بیشتر طول می‌کشد؛ بنابراین به وب‌هوک (webhook) نیاز دارید. در چنین سناریویی، وب‌هوک را با روش‌های نظرسنجی دوره‌ای (polling) و استریمینگ (streaming) مقایسه کنید. سپس با فرض این‌که ایجنت فقط قول می‌دهد هر تحویل را «حداقل یک‌بار» امتحان کند، و با در نظر گرفتن این‌که عملیات‌های پیکربندی اعتبارنامه‌های ذخیره‌شده‌ی وب‌هوک را به هر کسی که بتواند آن‌ها را فرابخواند برمی‌گردانند، وظایف گیرنده را فهرست کنید.

اول خودتان جواب بدهید، بعد پاسخ را باز کنید.

پاسخ کوتاه

پیکربندی را به‌صورت درون‌خطی (inline) در SendMessage همراه با returnImmediately: true ثبت کنید تا پیش از ایجاد پیکربندی هیچ رویدادی از دست نرود، و سپس اتصال را ببندید. تحویل از نوع حداقل یک‌بار (at-least-once) است؛ بنابراین ممکن است یک اعلان دوبار برسد یا پس از قطعی سرویس اصلاً دریافت نشود: گیرنده باید کد وضعیت 2xx برگرداند، شناسه‌ی وظیفه را بررسی کند، پردازش را بی‌اثر در تکرار (idempotent) انجام دهد، و پیش از هر اقدامی، وضعیت وظیفه را با GetTask بخواند. رمزی را که گیرنده اعتبارسنجی می‌کند در فیلد authentication بگذارید، زیرا token هدر استانداردی ندارد؛ همچنین دسترسی به فراخوانی چهار عملیات پیکربندی را محدود کنید، چرا که عملیات خواندن، اعتبارنامه‌ها را در قالب متن آشکار (clear text) برمی‌گرداند.

پاسخ کامل

سه روش برای انتظار

سازوکار باز نگه داشتن اتصال زمان باخبر شدن از تغییر هزینه هنگام راه‌اندازی مجدد کلاینت
نظرسنجی دوره‌ای با GetTask خیر در نظرسنجی بعدی هیچ، وظیفه ذخیره شده است
SendStreamingMessage یا SubscribeToTask بله بلافاصله از دست رفتن فریم‌ها؛ باید برای دریافت اسنپ‌شات دوباره سابسکرایب کنید
وب‌هوک خیر بلافاصله، پس از تحویل موفق از دست رفتن موارد تحویل؛ باید وظیفه را بخوانید

وب‌هوک برای کارهایی مناسب است که زمان اجرای آن‌ها از طول عمر فراخواننده بیشتر است. این روش مسئله‌ی نگه‌داشتن اتصال را به سمت گیرنده منتقل می‌کند و مرز اعتماد (trust boundary) دومی به معماری می‌افزاید.

چه داده‌ای دریافت می‌شود؟

هر اعلان یک درخواست HTTP POST است که بدنه‌ی آن یک شیء StreamResponse در قالب HTTP+JSON و بدون پوشش (envelope) پروتکل JSON-RPC است. در اجرای ثبت‌شده، اولین بدنه یک statusUpdate با وضعیت TASK_STATE_WORKING بود که با هدرهای Content-Type: application/a2a+json، Authorization: Bearer <secret> و X-A2A-Notification-Token ارسال شد. کتابخانه‌های SDK در نوع محتوا (content type)، هدر توکن و مهلت‌های زمانی (timeout) 5 یا 30 ثانیه‌ای با هم تفاوت دارند و هیچ‌کدام تلاش مجدد (retry) نمی‌کنند. بنابراین، هر دو نوع محتوا را بپذیرید، هر دو هدر توکن را بخوانید و تمام اعضای StreamResponse را مدیریت کنید؛ زیرا SDK مرجع، اولین Task را نیز ارسال می‌کند.

وظایف گیرنده

  1. برای تأیید دریافت، پاسخ با کد وضعیت 2xx بفرستید.
  2. بررسی کنید که شناسه‌ی وظیفه با وظیفه‌ای که انتظارش را دارید مطابقت داشته باشد.
  3. پردازش را بی‌اثر در تکرار انجام دهید. اعمال دوباره‌ی یک به‌روزرسانی وضعیت بر اساس شناسه‌ی وظیفه و برچسب زمان (timestamp) مشکلی ایجاد نمی‌کند. اما اعمال مجدد artifactUpdate در حالتی که append: true باشد امن نیست و هیچ شناسه‌ی تحویلی برای بررسی تکراری بودن وجود ندارد.
  4. هر اعلان را صرفاً یک سیگنال در نظر بگیرید و پیش از هر اقدامی، وظیفه را با GetTask بخوانید.
  5. مقدار Authorization را با اعتبارنامه‌ای که در authentication قرار داده‌اید تطبیق دهید.

وظایف ایجنت، و نقاط شکست احتمالی

ایجنت باید اعتبارنامه‌های پیکربندی‌شده را در هدرهای درخواست بگذارد و URL را در برابر حملات جعل درخواست سمت سرور (SSRF) اعتبارسنجی کند؛ به این ترتیب که بازه‌های خصوصی مانند 10.0.0.0/8 و 192.168.0.0/16 و همچنین آدرس‌های لوپ‌بک (loopback) و آدرس‌های محلی پیوند (link-local) را رد کند. اعتبارسنج SDK مرجع این کار را فقط در صورتی انجام می‌دهد که هاست آن را فعال کرده باشد. پیکربندی باید تا زمان اتمام وظیفه یا حذف آن توسط کلاینت باقی بماند، و عملیات حذف نیز باید بی‌اثر در تکرار باشد.

بده‌بستان‌ها

ثبت درون‌خطی هزینه‌ای در حد یک فیلد اضافی دارد و فاصله‌ی زمانی بین رویداد اول و ثبت پیکربندی را از بین می‌برد. قرار دادن رمز در authentication نیاز به تولید یک مقدار اختصاصی به‌ازای هر اجرا دارد، اما در عوض امکان بررسی اصالت را به گیرنده می‌دهد. بازگرداندن اعتبارنامه‌ها به‌صورت متن آشکار بهایی است که برای این چهار عملیات پیکربندی می‌پردازید؛ بنابراین دامنه‌ی دسترسی به آن‌ها را فقط به مالک وظیفه محدود کنید.

سؤال‌های تکمیلی مصاحبه‌گر
  • سطح 3: یک artifactUpdate با append: true دو بار دریافت می‌شود. چرا نمی‌توانید آن را دو بار اعمال کنید؟ پاسخ مورد انتظار: بخش‌های داده تکراری می‌شوند و شناسه‌ی تحویلی برای حذف موارد تکراری وجود ندارد؛ بنابراین باید در عوض کل وظیفه را بخوانید.
  • سطح 3: گیرنده به مدت یک دقیقه از دسترس خارج شد. چه چیزی را از دست داده است؟ پاسخ مورد انتظار: احتمالاً همه‌چیز را، زیرا هیچ‌کدام از SDKها تلاش مجدد ندارند؛ پس از بازگشت گیرنده، باید وظیفه را بخوانید.
  • سطح 4: چرا ایجنت باید URLهای وب‌هوک داخل بازه‌ی شبکه‌ی خصوصی را رد کند؟ پاسخ مورد انتظار: ایجنت برای تک‌تک رویدادهای بعدی وظیفه آن URL را فراخوانی می‌کند؛ بنابراین یک فراخواننده‌ی بیرونی می‌تواند درخواست‌های ایجنت را به سمت یک سرویس داخلی هدایت کند.
  • سطح 4: چه کسی مجاز به فراخوانی ListTaskPushNotificationConfigs است و چرا؟ پاسخ مورد انتظار: فقط مالک وظیفه، زیرا پاسخ این متد مقادیر credentials و token را بدون تغییر برمی‌گرداند.
جواب‌های اشتباهی که مصاحبه‌گرها زیاد می‌شنوند
  • «وب‌هوک را بعد از شروع وظیفه با عملیات ساخت (create) ثبت کنید.» رویدادهایی که پیش از ایجاد پیکربندی رخ می‌دهند از دست می‌روند. ثبت درون‌خطی هیچ فاصله‌ی زمانی باقی نمی‌گذارد.
  • «احراز هویت را روی هدر توکن انجام دهید.» در مشخصات استاندارد هیچ بستر انتقالی (transport) برای token تعریف نشده و SDKها از دو نام هدر مختلف استفاده می‌کنند. رمز را در authentication قرار دهید و Authorization را بررسی کنید.
  • «هر اعلان را بلافاصله پس از رسیدن اعمال کنید.» رویدادهای تکراری و تحویل‌های ازدست‌رفته هر دو اتفاق می‌افتند. وظیفه‌ی ذخیره‌شده منبع حقیقت (source of truth) است.

کجای دوره آموزش داده می‌شود

بخش اعلان‌های push هشت تحویل و جدول SDKها را مستند کرده است، و بخش الزامات امنیتی قوانین وب‌هوک را برمی‌شمارد.