Notificationهای log و progress (Log & progress notifications)

عنوان اصلی: Log & progress notifications

هدف یادگیری: stream کردن پیام‌های log و updateهای progress از یک عملیات طولانی server به client.

مفاهیم کلیدی: capability logging، logging/setLevel، notifications/message، سطوح RFC 5424 (debug, info, notice, warning, error, critical, alert, emergency)، progressToken در _meta، notifications/progress (progress, total, message).

دو utility primitive مستقل:

Logging — server "logging": {} را اعلام می‌کند؛ client می‌تواند logging/setLevel را با یک رشته level صدا بزند؛ server notifications/message را با level، logger و JSON دلخواه data emit می‌کند. سطوح log از syslog (RFC 5424) پیروی می‌کنند. سرورها نباید credentialها، PII یا جزئیات داخلی سیستم را log کنند.

Progress — sender یک progressToken (string یا integer، یکتا روی requestهای فعال) داخل فیلد _meta request می‌گذارد؛ receiver می‌تواند یک یا چند notifications/progress با همان token به‌علاوه یک مقدار progress به‌صورت یکنوای صعودی، total اختیاری و message انسانی اختیاری emit کند. progress ابزار درست برای «این tool ۳۰ ثانیه طول می‌کشد، لطفاً timeout نکن» است — و clientها بهتر است هر وقت progress می‌رسد timeout request را reset کنند (با یک سقف سخت).

مثال عملی — JSON خام (request با progress token)

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {
    "name": "build_index",
    "arguments": { "path": "./docs" },
    "_meta": { "progressToken": "build-42" }
  } }

مثال عملی — JSON خام (notification progress)

{ "jsonrpc": "2.0", "method": "notifications/progress",
  "params": {
    "progressToken": "build-42",
    "progress": 50, "total": 100,
    "message": "Indexing chapter 3 of 6..."
  } }

مثال عملی — JSON خام (پیام log)

{ "jsonrpc": "2.0", "method": "notifications/message",
  "params": {
    "level": "error",
    "logger": "database",
    "data": { "error": "Connection failed",
              "details": { "host": "localhost", "port": 5432 } }
  } }

اشتباهات رایج

• ارسال progress با token که روی request فعال نیست. clientها ignore می‌کنند (یا بدتر، error می‌دهند).
• کم کردن progress بین notificationها. spec الزام می‌کند صعود یکنوا.
• log کردن سکرت. spec credential، PII و جزئیات داخلی را در payload notifications/message ممنوع می‌کند.