سناریوی رخداد

یک خطا، دو وضعیت پاسخ

One error, two status codes

  • سطح ۲: میانی
  • سناریوی رخداد
  • ۲۰ دقیقه

وضعیت

یک سیستم برنامه‌ریز (planner)، اجرای تست‌ها را به یک ایجنت مخزن راه‌دور به نام test-runner واگذار می‌کند. لایه‌ی بستر انتقال این سیستم برای یک سرویس REST معمولی نوشته شده است: پاسخ 2xx یعنی موفقیت؛ کد 404 یعنی رکورد هنوز در دسترس نیست، پس کلاینت منتظر می‌ماند و دوباره درخواست می‌فرستد؛ و کدهای 5xx هم مشمول تلاش مجدد با عقب‌گرد می‌شوند. برنامه‌ریز ابتدا از طریق رابط JSON-RPC با این ایجنت ارتباط برقرار می‌کرد. دیشب شناسه‌ی وظیفه‌ای (task id) را استعلام کرد که ایجنت آن را پاک کرده بود؛ برنامه‌ریز این استعلام را به عنوان عملیات موفق ثبت کرد و سپس به دلیل خالی بودن نتیجه دچار کرش شد.

صبح امروز، یکی از هم‌تیمی‌ها ارتباط برنامه‌ریز را به رابط HTTP+JSON ایجنت تغییر داد «تا کدهای وضعیت واقعی دریافت کنیم». حالا همان استعلام با کد 404 برمی‌گردد و برنامه‌ریز به مدت یک ساعت، هر 2 ثانیه یک بار دوباره همان درخواست را تکرار کرده است. از شما خواسته شده کاری کنید که کلاینت در هر دو پیوند پروتکل (binding) در زمان مناسب متوقف شود، بدون اینکه برای تک‌تک خطاها حالت خاص جداگانه‌ای تعریف کنید.

نسخه
A2A 1.0.1 with the manual's capture kit (the test-runner, code-reviewer and deployer agents)
مدل
no model; the agents are deterministic fixtures
سخت‌افزار
one machine, localhost, no network

شواهد

error-table.txt
title: every A2A error with its code in each binding
source: manuals/a2a-101/sections/r-4-errors.md
lines: 7-24
lang: text
note: Count how many rows share HTTP 400, and which rows have no HTTP status at all.
---
| Error | JSON-RPC | HTTP | gRPC |
|---|---|---|---|
| TaskNotFoundError | -32001 | 404 | NOT_FOUND |
| TaskNotCancelableError | -32002 | 400 | FAILED_PRECONDITION |
| PushNotificationNotSupportedError | -32003 | 400 | FAILED_PRECONDITION |
| UnsupportedOperationError | -32004 | 400 | FAILED_PRECONDITION |
| ContentTypeNotSupportedError | -32005 | 400 | INVALID_ARGUMENT |
| InvalidAgentResponseError | -32006 | 500 | INTERNAL |
| ExtendedAgentCardNotConfiguredError | -32007 | 400 | FAILED_PRECONDITION |
| ExtensionSupportRequiredError | -32008 | 400 | FAILED_PRECONDITION |
| VersionNotSupportedError | -32009 | 400 | FAILED_PRECONDITION |
| JSONParseError | -32700 | none | none |
| InvalidRequestError | -32600 | none | none |
| MethodNotFoundError | -32601 | none | none |
| InvalidParamsError | -32602 | 400 | INVALID_ARGUMENT |
| InternalError | -32603 | 500 or 503 | INTERNAL or UNAVAILABLE |
| Authentication error | custom | 401 | UNAUTHENTICATED |
| Authorization error | custom | 403 | PERMISSION_DENIED |
jsonrpc-lookup.txt
title: a GetTask for an unknown id over JSON-RPC, status and code
source: manuals/a2a-101/capture/out/11-errors.http
lines: 1-26
lang: text
note: Read the HTTP status line, then the member that replaced result and its code.
---
### 1 · GetTask: an id that does not exist
POST /a2a/jsonrpc HTTP/1.1
Host: localhost:41241
Content-Type: application/json
A2A-Version: 1.0

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "GetTask",
  "params": {
    "id": "00000000-0000-4000-8000-000000000000"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Task not found",
    "data": [
      {
jsonrpc-reason.txt
title: the detail inside data of the same JSON-RPC error
source: manuals/a2a-101/capture/out/11-errors.http
lines: 28-36
lang: text
note: The reason and the domain name the error. The metadata repeats the id that was asked for.
---
        "reason": "TASK_NOT_FOUND",
        "domain": "a2a-protocol.org",
        "metadata": {
          "taskId": "00000000-0000-4000-8000-000000000000"
        }
      }
    ]
  }
}
rest-lookup.txt
title: the same lookup over HTTP+JSON, status and body head
source: manuals/a2a-101/capture/out/16-rest-binding.http
lines: 180-194
lang: text
note: Compare the status line with the code and status fields of the body.
---
### 3 · GET /tasks/{id}: not found
GET /a2a/rest/tasks/00000000-0000-4000-8000-000000000000 HTTP/1.1
Host: localhost:41241
A2A-Version: 1.0

HTTP/1.1 404 Not Found
Content-Type: application/a2a+json

{
  "error": {
    "code": 404,
    "status": "NOT_FOUND",
    "message": "Task not found",
    "details": [
      {
rest-reason.txt
title: the detail inside the HTTP+JSON error
source: manuals/a2a-101/capture/out/16-rest-binding.http
lines: 196-204
lang: text
note: Compare the reason with the one in the JSON-RPC reply.
---
        "reason": "TASK_NOT_FOUND",
        "domain": "a2a-protocol.org",
        "metadata": {
          "taskId": "00000000-0000-4000-8000-000000000000"
        }
      }
    ]
  }
}
retry-rules.txt
title: which errors a client may retry
source: manuals/a2a-101/sections/5-5-errors.md
lines: 116-125
lang: text
note: Each line names the codes and the one action that fits them. The last line is about a retried send.
---
Most A2A errors describe the request or the task, so resending the same bytes gets the same answer:

- `-32603`, HTTP `500` or `503`, or a dropped connection: retry with backoff, and honor `Retry-After` {{spec §3.3.2}}.
- HTTP `401`: get a fresh credential, then retry.
- `-32600`, `-32602`, `-32005`, `-32009`, and their `400` forms: fix the request before you send it again.
- `-32001`: stop, because the id is wrong, purged, or hidden from you {{spec §3.3.2}}.
- `-32002`, or `-32004` on a terminal task: start a new task, as [CancelTask and terminal states](#s-cancel-task-and-terminal-states) shows.
- `-32003`, `-32007`, or `-32004` from a capability check: read the card again.

A retried `SendMessage` can start a second task, because duplicate detection by `messageId` is optional {{spec §3.3.1}}. Send the same `messageId` anyway, as [Message](#s-message) explains.

سؤال‌ها

  1. در پاسخ JSON-RPC، ناموفق بودن استعلام در کجای پیام مشخص شده است و وضعیت HTTP چه چیزی را نشان می‌دهد؟
  2. کدام فیلد در هر دو پاسخ کاملاً یکسان است و کدام فیلدها تفاوت دارند؟
  3. چند مورد از 9 خطای پروتکل A2A کد وضعیت HTTP یکسانی دارند و این موضوع چه تأثیری روی منطقی می‌گذارد که فقط بر اساس کد وضعیت عمل می‌کند؟
  4. کلاینت برای کدام خطاها مجاز به تلاش مجدد است و در مواجهه با وظیفه‌ای که پیدا نمی‌شود چه واکنشی باید نشان دهد؟
  5. برنامه‌ریز پس از اتمام مهلت زمانی (timeout)، برای SendMessage هم تلاش مجدد می‌کند. در این حالت چه چیزی باید بدون تغییر بماند و چرا؟

اول شواهد را بخوانید و به سؤال‌ها جواب بدهید، بعد راه‌حل را باز کنید.

راه‌حل گام‌به‌گام
  1. پاسخ JSON-RPC را بررسی کنید. خط وضعیت عبارت 200 OK را نشان می‌دهد و در بدنه خبری از result نیست. به‌جای آن، یک عضو error با کد 32001- و پیام Task not found قرار دارد. در این پیوند، تمام پاسخ‌ها با کد 200 ارسال می‌شوند؛ بنابراین وضعیت HTTP هیچ اطلاعات مفیدی به همراه ندارد. کلاینت پیش از تلاش برای خواندن result، باید بدنه را باز کرده و وجود error را بررسی کند.
  2. جزئیات درون data را بررسی کنید. این بخش لیستی شامل یک شیء است؛ مقدار reason در آن برابر با TASK_NOT_FOUND، مقدار domain برابر با a2a-protocol.org، و بخش metadata تکرارکننده‌ی همان شناسه‌ی وظیفه است. فیلد reason همان نام خطاست بدون پسوند آن؛ این دقیقاً همان فیلدی است که کلاینت می‌تواند بر اساس آن تصمیم‌گیری کند.
  3. پاسخ HTTP+JSON را بررسی کنید. خط وضعیت کد 404 Not Found را نشان می‌دهد. بدنه شامل یک شیء Status با code برابر 404، status برابر NOT_FOUND، همان متن پیام، و فیلد details است (جایی که در JSON-RPC نامش data بود). داخل details دقیقاً همان شیء جزئیات با همان reason قرار دارد. پوسته‌ی پیام تغییر کرده، اما اصل خطا دست‌نخورده باقی مانده است.
  4. جدول را بررسی کنید. 7 مورد از 9 خطای A2A به کد HTTP 400 نگاشت می‌شوند و InvalidParamsError نیز به 400 تبدیل می‌شود. 3 خطای مربوط به تجزیه (parse) و ساختار درخواست در JSON-RPC اصلاً هیچ کد وضعیت معادل HTTP ندارند. بنابراین، قاعده‌ای که فقط بر پایه‌ی وضعیت HTTP عمل کند، نمی‌تواند تفاوتی بین وظیفه‌ای که امکان لغو ندارد و درخواستی با فیلدهای نامعتبر قائل شود. از طرفی فقط TaskNotFoundError به 404 نگاشت می‌شود؛ در نتیجه یک رویکرد REST که منتظر رفع 404 می‌ماند، عملاً در انتظار خطایی معطل می‌شود که هرگز برطرف نخواهد شد.
  5. قواعد تلاش مجدد را اعمال کنید. در صورت دریافت 32603-، کدهای HTTP 500 یا 503، یا قطع شدن اتصال: تلاش مجدد همراه با عقب‌گرد و رعایت مقدار Retry-After. در صورت دریافت HTTP 401: دریافت اعتبارنامه‌ی جدید. در صورت دریافت 32600-، 32602-، 32005- و 32009-: اصلاح ساختار درخواست. در صورت دریافت 32001-: توقف عملیات؛ چرا که شناسه اشتباه است، پاک شده یا از این فراخواننده مخفی شده است. در صورت دریافت 32002-، یا 32004- روی وظیفه‌ای که به وضعیت پایانی رسیده: شروع یک وظیفه‌ی جدید. در صورت دریافت 32003- یا 32007-: خواندن دوباره‌ی کارت ایجنت. سرور نباید اطلاعات وظیفه‌ای را که فراخواننده اجازه‌ی دیدنش را ندارد فاش کند؛ بنابراین «یافت نشد» می‌تواند به معنای «متعلق به شما نیست» هم باشد.
  6. سایر سناریوهای تلاش مجدد را بررسی کنید. یک فراخوانی SendMessage که مهلت زمانی آن تمام شده، ممکن است در سمت سرور وظیفه‌ای ایجاد کرده باشد. از آنجا که شناسایی درخواست‌های تکراری با استفاده از messageId امری اختیاری است، ارسال مجدد با یک شناسه‌ی جدید ممکن است وظیفه‌ی دومی را کلید بزند. برنامه‌ریز همان بایت‌ها را با همان messageId قبلی دوباره می‌فرستد تا سرور تنها شانس خود را برای تشخیص تکراری بودن درخواست داشته باشد.
نتیجه

کلاینت صرفاً بستر انتقال را رمزگشایی می‌کرد و کاری به خود پروتکل نداشت. راهکار اصلی، پیاده‌سازی یک پردازنده‌ی خطای مشترک برای هر دو پیوند است: ابتدا وضعیت HTTP خوانده شود، سپس عضو error یا بدنه‌ی Status، و در نهایت مقدار reason از اولین شیء موجود در جزئیات خطا. سپس بر اساس این reason دسته‌بندی انجام گیرد: تلاش مجدد، احراز هویت دوباره، اصلاح درخواست یا توقف عملیات. در صورت مواجهه با TASK_NOT_FOUND، برنامه‌ریز در هر دو پیوند تنها پس از یک بار دریافت پاسخ متوقف می‌شود؛ درست همان رفتاری که در ثبت وقایع دیده می‌شود: یک درخواست و یک پاسخ برای شناسه‌ی نامشخص در JSON-RPC، و یک درخواست و یک پاسخ در HTTP+JSON. در تلاش‌های مجدد برای ارسال، messageId حفظ می‌شود. دیگر خبری از یک ساعت استعلام بیهوده و پیاپی نخواهد بود؛ چون تصمیم‌گیری سیستم دیگر وابسته به کد وضعیتی نیست که در یکی از این پیوندها اصلاً استفاده نمی‌شود.

مسیرهای اشتباه رایج
  • «همه‌ی کلاینت‌ها را به HTTP+JSON منتقل کنیم تا کدهای وضعیت واقعی شوند.» 7 خطا از 9 خطای پروتکل A2A در آنجا با کد 400 برمی‌گردند و در کنار پارامترهای نامعتبر قرار می‌گیرند؛ بنابراین کد وضعیت همچنان نام خطا را مشخص نمی‌کند.
  • «تطبیق بر اساس متن پیام خطا (Message).» متن پیام برای انسان نوشته شده است. پیاده‌سازی مرجع در همین شرایط از واژه‌ها و نام فیلدهای دیگری استفاده می‌کند؛ بنابراین تطبیق متن روی سرور بعدی از کار می‌افتد.
  • «در نظر گرفتن کد 404 به عنوان همگرایی نهایی (eventual consistency) و ادامه‌ی پولینگ.» طبق مشخصات پروتکل، سرور برای شناسه‌ی پاک‌شده و همچنین وظیفه‌ای که فراخواننده دسترسی دیدنش را ندارد، خطای not found برمی‌گرداند. هیچ فراخوانی بعدی این پاسخ را تغییر نخواهد داد.
  • «ارسال مجدد با یک messageId جدید برای احتیاط.» تشخیص درخواست تکراری اختیاری است و شناسه‌ی جدید تنها نشانه‌ای را که سرور برای تشخیص این موضوع دارد از بین می‌برد؛ در نتیجه ممکن است کل مجموعه تست‌ها 2 بار اجرا شود.
درس کلی

پروتکلی که روی بستر HTTP منتقل می‌شود، دو لایه‌ی وضعیت دارد: وضعیت بستر انتقال که فقط رسیدن یا نرسیدن بایت‌ها را اعلام می‌کند، و خطای خود پروتکل که مشخص می‌کند چه بر سر درخواست آمده است (خطایی که در برخی پیوندها پشت یک کد 200 پنهان می‌شود). بر اساس تفکیک‌کننده‌ی خود پروتکل تصمیم بگیرید، مجموعه‌ی خطاهای قابل تلاش مجدد را محدود و صریح نگه دارید، و برای هر تلاش مجدد، یک کلید یکتایی تراکنش بفرستید که برای سرور قابل مشاهده باشد.

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

در بخش خطاهای راهنمای A2A 101 این دو پاسخ خوانده شده و قواعد تلاش مجدد آمده است؛ در جدول خطاها نحوه‌ی نگاشت هر خطا در 3 پیوند مختلف مشخص شده، و در درس حالت‌های شکست زنجیره‌ای که در پی ناتوانی کلاینت در تشخیص شکست از موفقیت رخ می‌دهد، بررسی شده است.