Java-Python 음성 경계를 gRPC 계약으로 고정하기

Java API와 Python 음성 엔진은 서로 다른 프로세스이므로, 문자열 기반 내부 호출보다 protobuf 계약이 변경과 장애를 더 분명하게 만든다. voice/v1/voice.proto는 음성 합성·voice catalog·capability를 하나의 버전 경계로 묶고, Java client는 요청 deadline을 넘기지 않는다.

계약의 핵심

• Synthesize는 provider, text, voice, request ID를 받고 audio bytes와 content type, duration, provider를 반환한다.
• Python server는 텍스트·request ID·메시지 크기를 제한하고, provider 예외 본문이나 입력 text를 외부 오류로 복사하지 않는다.
• Java client의 blocking stub은 bounded elastic 실행기에서 실행하며, gRPC가 꺼져 있거나 실패하면 기존 REST TTS 경계로 명시적으로 fallback한다.
• public REST API는 유지한다. gRPC는 내부 서비스 간 비용·계약 경계이며, 모든 API를 gRPC로 바꾸는 목표가 아니다.

완료 기준

1. proto 생성 코드가 Java와 Python 빌드에서 같은 source를 사용한다.
2. deadline 초과·provider 오류·gRPC 비활성화가 안전한 오류 종류와 REST fallback으로 관측된다.
3. Spring MDC의 요청 ID가 있으면 protobuf request_id로 전달하되, 고카디널리티 사용자 입력을 로그 키로 만들지 않는다.
4. GetCapabilities와 /health/capabilities가 실제 server lifecycle과 일치한다.

관련 강좌: gRPC·WebRTC 실시간 경계를 비용 가드로 닫기