Type Server Protocol - Python 타입 분석 데이터를 조회하는 JSON-RPC 프로토콜

무엇인가

Type Server Protocol(TSP)은 타입 서버에 Python 분석 데이터를 요청하는 JSON-RPC 프로토콜이에요. 타입 서버는 워크스페이스의 타입 분석 상태를 유지하고 다음 요청에 답해요.

• 프로토콜 버전
• 스냅숏
• Python 검색 경로
• import 해석
• 타입 질의(계산된 타입, 선언된 타입, 기대 타입)

Position, Range 같은 LSP 자료형과 관례를 쓸모 있는 곳에 그대로 쓰고, URI도 LSP처럼 문자열로 표현해요. 메서드는 typeServer/ 접두사를 붙여요. 정식 정의는 typeServerProtocol.ts(TypeScript 인터페이스), tsp.json(기계 판독 모델), tsp.schema.json(JSON 스키마)이에요.

버전

semver로 호환성을 확인하고, 0.x 동안은 마이너 버전 변경이 호환을 깰 수 있어요.

| 버전 | 변경 | |---|---| | 0.1.0 | 첫 버전 | | 0.2.0 | 요청 타입·필드 추가 | | 0.3.0 | 더 복잡한 타입 형태로 전환 | | 0.4.0 | Type 유니온과 스텁 기반 타입 페이로드 | | 0.4.1 | 다중 연결 협상과 typeServer/connection 요청 추가 |

연결과 세션 흐름

클라이언트가 타입 서버를 띄우고 stdio나 Node IPC로 메인 JSON-RPC 연결을 맺어요. stdio를 쓰면 stdout은 프로토콜 메시지 전용이에요.

1. LSP initialize/initialized로 공유 상태 초기화
2. typeServer/getSupportedProtocolVersion으로 버전 호환 확인
3. typeServer/getSnapshot으로 첫 스냅숏 ID 획득
4. 스냅숏을 담아 타입 질의, import 해석, 검색 경로 요청
5. 이전 결과가 무효가 되면 서버가 typeServer/snapshotChanged 전송

다중 연결 모드

선택적인 성능 기능이에요. 대량 타입 질의나 백그라운드 작업처럼 읽기 전용 요청을 추가 로컬 채널로 동시에 처리하고, 변경 가능한 워크스페이스 상태는 메인 연결이 계속 맡아요. LSP initialize의 capabilities.experimental.typeServerMultiConnection으로 양쪽이 지원 전송 방식(현재 ipc)을 알리고, 겹치는 게 있을 때만 켜져요. 이후 typeServer/connection에 {"type":"open","kind":"ipc"}를 보내 채널을 열어요. 단일 연결에서도 서버는 올바르게 동작해야 해요.

문서 앞부분(개요, 버전, 연결 모델, 다중 연결 협상)을 기준으로 옮겼어요. 개별 요청 정의는 다 옮기지 않았어요.