마이크로소프트가 파이썬 분석 엔진 파이랜스(Pylance)의 저장소에 타입 서버 프로토콜(Type Server Protocol, 이하 TSP) 명세를 공개했다. TSP는 '타입 서버'에 파이썬 분석 데이터를 요청하기 위한 JSON-RPC 기반 프로토콜이다. 여기서 타입 서버란 워크스페이스의 타입 분석 상태를 유지하면서 프로토콜 버전, 스냅샷, 파이썬 검색 경로, 임포트 해석, 그리고 타입 질의에 응답하는 구성 요소를 말한다. 그동안 에디터와 언어 분석기 사이를 잇는 표준은 언어 서버 프로토콜(LSP)이 사실상 독점해 왔는데, TSP는 그 흐름 위에서 '타입 정보'라는 더 좁고 전문적인 영역을 별도로 떼어내 다룬다는 점에서 눈여겨볼 만하다.
LSP 위에서 동작하는 전문 프로토콜
TSP는 완전히 새로운 체계를 만들기보다 LSP의 자산을 적극적으로 재활용한다. 위치를 나타내는 Position과 Range, 문자열로 표현하는 URI 등 LSP의 데이터 형태와 관례를 그대로 쓰고, 자신만의 메서드에는 typeServer/ 접두사를 붙인다. 통신 방식도 익숙하다. 클라이언트가 타입 서버를 기동한 뒤 stdio나 Node IPC 같은 전송 수단 위에서 하나의 JSON-RPC 연결로 대화하며, stdio를 쓸 때는 stdout을 프로토콜 메시지 전용으로 비워 둬야 한다. 실제 운용에서는 일반적인 LSP 초기화와 문서 동기화로 워크스페이스·문서 상태를 먼저 전달한 다음, 같은 연결 위에서 typeServer/* 요청을 보내는 형태가 된다. 즉 기존 LSP 통합에 타입 질의 계층을 얹는 구조라 도입 장벽이 낮다.
버전 관리에는 시맨틱 버저닝을 쓰되 주의할 점이 있다. 현재 0.x 대에서는 마이너 버전이 올라가도 하위 호환이 깨질 수 있고, 패치 버전만 같은 마이너 라인 안에서 호환이 보장된다. 아직 안정화 이전 단계라는 신호이므로, 클라이언트와 서버는 반드시 버전 호환성 검사를 거쳐야 한다.
멀티 연결은 성능을 위한 선택지
TSP는 선택적으로 읽기 전용 보조 연결을 열 수 있다. 다만 원래의 메인 연결이 초기화, 워크스페이스 상태, 문서 동기화, 상태를 바꾸는 알림, 연결 제어를 모두 소유하며, 보조 연결은 양쪽이 초기화 단계에서 지원을 협상한 뒤에만 열린다. 이 멀티 연결 모드는 어디까지나 성능 기능이다. 대량 타입 질의나 메인 연결을 막아서는 안 되는 백그라운드 작업처럼 동시 읽기 작업의 이득이 분명할 때만 쓰도록 권고된다. 서버는 단일 연결 모드에서도 올바르게 동작해야 하며, 멀티 연결 지원이 프로토콜 정확성의 전제가 되어서는 안 된다.
협상은 LSP의 initialize 요청과 응답을 통해 이뤄진다. 양쪽이 capabilities.experimental.typeServerMultiConnection 아래 지원 전송 종류를 광고하고, 두 목록에 공통 전송이 하나라도 있을 때만 활성화된다. 한쪽이라도 해당 역량을 생략하거나 공통 전송이 없으면 세션은 단일 연결로 남고, 클라이언트는 typeServer/connection을 보내서는 안 된다. 현재 보조 연결에 쓸 수 있는 내장 전송은 ipc뿐이며, 이는 stdio나 Node IPC를 쓸 수 있는 메인 연결의 협상과는 별개다. 채널을 열 때는 메인 연결에서 typeServer/connection을 보내 엔드포인트를 지정하고, 서버는 요청을 검증해 신속히 연결한 뒤 성공 여부를 반환한다. 전이중 스트림이면 엔드포인트 하나, 단방향 스트림만 지원하는 플랫폼이면 서버 입력·출력 두 개의 문자열을 전달한다. 보조 연결은 TSP 전용이자 읽기 전용이므로, 서버는 그 위로 들어온 LSP 트래픽이나 상태 변경 알림, 해당 TSP 버전에서 허용되지 않은 메시지를 거부해야 한다.
스냅샷과 타입 핸들의 생명 주기
TSP를 이해하는 핵심 개념은 스냅샷이다. 스냅샷은 분석 상태의 특정 시점 뷰를 가리키는 음이 아닌 정수이며, 타입 핸들·선언·심벌 같은 반환 객체는 명시적 예외가 없는 한 해당 스냅샷 안에서만 유효하다. 서버는 이전에 돌려준 분석 결과가 무효가 될 수 있는 사건, 가령 열린 파일의 변경, 파일 닫힘, 설정 변경, 감시 파일 변경, 의존성 변경, 캐시 재설정 등이 일어나면 스냅샷을 전진시켜야 한다. 위치 정보를 다른 인코딩으로 저장하는 서버라면 프로토콜 경계에서 반드시 변환해야 하는데, 변환이 틀리면 클라이언트가 엉뚱한 구문 노드의 정보를 요청하게 된다.
타입 질의 요청은 getComputedType, getDeclaredType, getExpectedType 세 가지로, 같은 노드나 선언에 대해 각각 계산된 타입, 선언된 타입, 기대되는 타입을 보고한다는 점에서 갈린다. 대상은 URI와 소스 범위로 된 노드이거나, 심벌이 정의된 위치와 방식을 기술하는 선언으로 지정한다. 선언은 소스 AST 노드가 뒷받침하는 일반 선언과, 타입 검사기가 만들어 소스 노드가 없는 합성 선언으로 나뉜다. 반환되는 타입 결과는 판별자(discriminator)를 품은 JSON 직렬화 가능 태그 객체로, 내장 타입·함수·클래스·유니언·모듈·타입 변수·오버로드 집합·합성 타입·타입 참조 등을 표현한다. 각 타입 객체는 숫자 kind 판별자와 숫자 id, 플래그 비트필드를 지니며, 유효하지 않은 핸들은 -1(InvalidHandle)이라는 센티넬 값으로 처리한다. 타입 id는 응답 단위로만 유효하고 객체 자체도 스냅샷에 묶인다는 점을 혼동해선 안 된다.
실무자가 눈여겨볼 지점과 한계
실무적으로 TSP가 의미 있는 이유는 타입 정보의 '생산자'와 '소비자'를 분리할 가능성을 열기 때문이다. 지금까지 파이썬 타입 정보는 각 도구가 자체 엔진에 가둬 두는 경우가 많았는데, 표준 질의 프로토콜이 있으면 린터, 테스트 러너, 문서 생성기, 리팩터링 도구 같은 외부 클라이언트가 동일한 타입 서버에 질의해 중복 분석을 피할 수 있다. 특히 스냅샷 기반 일관성 모델과 읽기 전용 멀티 연결은 대규모 코드베이스에서 백그라운드 작업이 편집 응답성을 해치지 않도록 설계됐다.
다만 현 시점의 한계도 분명하다. 프로토콜은 의도적으로 작게 유지되고 있고, 0.x 버전이라 마이너 변경에서 호환성이 깨질 수 있어 아직 실험 단계로 보는 편이 안전하다. 보조 연결 전송은 ipc 하나뿐이며 멀티 연결 역량도 experimental 네임스페이스 아래 있다. 정확한 파라미터와 결과 형태는 저장소의 프로토콜 아티팩트가 권위 있는 정의이고, 공개된 문서는 Pylance 2026.4.1 기준으로 정렬돼 있다. 결국 지금 단계에서 TSP는 당장 도입할 완제품 표준이라기보다, 마이크로소프트가 파이썬 타입 분석을 어떤 인터페이스로 개방하려 하는지 보여주는 설계 청사진에 가깝다. 타입 기반 도구를 만들거나 에디터 통합을 고민하는 팀이라면, 명세의 방향성과 버전 정책을 지금부터 따라가 둘 가치가 있다.