‏Type Server Protocol: پروتکل مایکروسافت برای گرفتن تایپ‌های پایتون

مایکروسافت تو مخزن pylance-release سند کامل Type Server Protocol یا TSP رو گذاشته. TSP یه پروتکل JSON-RPC هست (یعنی پیام‌ها به شکل JSON بین کلاینت و سرور رد و بدل می‌شن) برای پرسیدن اطلاعات تایپ پایتون از یه type server. type server برنامه‌ایه که وضعیت تحلیل تایپ کل workspace رو نگه می‌داره و به سوال‌هایی مثل نسخه‌ی پروتکل، مسیرهای جستجوی پایتون، resolve کردن importها و خود تایپ‌ها جواب می‌ده.

TSP تا جای ممکن از ساختارهای LSP (یعنی Language Server Protocol که ادیتورها باهاش با سرور زبان حرف می‌زنن) استفاده می‌کنه، مثل Position و Range. همه‌ی متدهاش هم با پیشوند typeServer/ شروع می‌شن. کلاینت معمولاً با همون initialize معمولی LSP شروع می‌کنه، بعد با typeServer/getSupportedProtocolVersion نسخه رو چک می‌کنه. نسخه‌ی فعلی 0.4.1 هست و تا وقتی پروتکل تو خط 0.x باشه، تغییر نسخه‌ی minor ممکنه سازگاری رو بشکنه.

مفهوم اصلی این پروتکل snapshot هست، یعنی یه عدد صحیح که یه لحظه از وضعیت تحلیل سرور رو نشون می‌ده. هر جوابی که سرور می‌ده فقط برای همون snapshot معتبره. هر وقت فایلی عوض بشه یا تنظیمات و dependencyها تغییر کنن، سرور باید snapshot رو جلو ببره و typeServer/snapshotChanged بفرسته. اگه کلاینت با snapshot کهنه درخواست بده، خطای -32802 (همون ServerCancelled تو LSP) می‌گیره و باید با snapshot تازه دوباره امتحان کنه.

سه نوع سوال تایپ داریم. getComputedType تایپی رو می‌ده که از جریان کد استنتاج شده. getDeclaredType تایپیه که صریحاً تو کد نوشته شده، مثلاً برای def foo(a: int | str) می‌شه int | str. getExpectedType هم تایپیه که اطراف کد انتظارش رو داره، مثل آرگومان foo(4). جواب‌ها آبجکت‌های JSON هستن با یه فیلد عددی kind که می‌گه با کلاس، تابع، union، ماژول یا TypeVar سروکار داریم.

تو نسخه‌ی 0.4.1 یه قابلیت اختیاری برای سرعت اضافه شده به اسم multi-connection mode. یعنی کلاینت می‌تونه کنار اتصال اصلی، چند کانال IPC اضافه به همون سرور باز کنه و درخواست‌های فقط-خواندنی مثل type query رو موازی بفرسته. این قابلیت تو initialize با کلید typeServerMultiConnection اعلام می‌شه و فقط وقتی فعاله که هر دو طرف حداقل یه transport مشترک داشته باشن:

{
    "capabilities": {
        "experimental": {
            "typeServerMultiConnection": {
                "supportedTransports": ["ipc"]
            }
        }
    }
}

کانال اضافه با درخواست typeServer/connection روی اتصال اصلی باز و بسته می‌شه. هر کاری که وضعیت رو عوض می‌کنه، مثل همگام‌سازی سندها و تنظیمات، فقط روی اتصال اصلی می‌مونه و سرور باید اینا رو روی کانال‌های اضافه رد کنه. سرور باید بدون این حالت هم درست کار کنه، یعنی multi-connection فقط یه بهینه‌سازیه، نه پیش‌نیاز.

نکات کلیدی:

• TSP یه پروتکل JSON-RPC برای گرفتن اطلاعات تایپ پایتون از type server هست و متدهاش پیشوند typeServer/ دارن.
• نسخه‌ی فعلی 0.4.1 هست و تو خط 0.x تغییر minor می‌تونه breaking باشه.
• درخواست با snapshot کهنه خطای -32802 (ServerCancelled) می‌گیره و کلاینت باید با snapshot جدید دوباره بفرسته.
• موقعیت‌ها مثل LSP صفرمبنا و بر اساس واحدهای UTF-16 حساب می‌شن.
• multi-connection فعلاً فقط transport نوع ipc رو پشتیبانی می‌کنه و فقط برای درخواست‌های فقط-خواندنیه.
• سند با Pylance نسخه‌ی 2026.4.1 هماهنگه.