infra: gRPC proto 단일 source-of-truth (api-server ↔ ai-server)

[cocoyoon]

요약

api-server(Rust)와 ai-server(Python)가 gRPC로 통신할 때 .proto가 두 곳에 있어 드리프트가 발생함. packages/grpc-proto/를 단일 정본으로 두고 양쪽 빌드·코드 생성이 이 경로만 참조하도록 정리한다.

배경

• Rust: packages/api-server/build.rs가 packages/api-server/proto/ai.proto, proto/backend/backend.proto 컴파일
• Python: packages/ai-server/src/grpc/proto/inbound|outbound/*.proto를 수동 grpc_tools.protoc로 생성 (src/grpc/README.md 참고)

문제

• 동일 package인데 내용 불일치 (예: outbound LinkMetadata — Rust 쪽은 citations=4·keywords=5·link_type=6, Python proto는 필드 번호·구성이 다름 → 와이어 호환 위험)
• inbound: api ai.proto에만 ProcessDataBatch RPC 잔존 — Rust 클라이언트 미사용(decoded_ai_grpc/client.rs), AI 서버도 Phase 8에서 제거됨

목표

하나의 디렉터리만 편집하고, Rust·Python 생성 코드가 모두 그 정본에서 나오게 함.

flowchart LR
  subgraph sot [packages/grpc-proto]
    inboundProto[inbound.proto]
    outboundProto[outbound.proto]
  end
  sot --> buildRs[api-server build.rs]
  buildRs --> rustGen[tonic/prost]
  sot --> pyScript[gen-proto script]
  pyScript --> pyGen[pb2 / pb2_grpc]

Loading

권장 레이아웃

• packages/grpc-proto/inbound.proto — package inbound;, service Queue
• packages/grpc-proto/outbound.proto — package outbound;, service Metadata

정본 내용 (합의안)

inbound

• RPC/메시지는 실제 구현·호출과 일치: MetadataServicer ↔ DecodedAIGrpcClient
• ProcessDataBatch 및 DataItem / ProcessDataBatchRequest|Response 제거
• ExtractOGDataResponse 등은 Python이 채우는 필드 + Rust metadata/service.rs 사용처 기준 정합
• api ai.proto에만 있던 독립 LinkMetadata 메시지(미참조)는 정본에서 삭제해 Python과 메시지 집합 통일

outbound

• 정본은 packages/api-server/proto/backend/backend.proto와 동일 와이어 (backend_grpc/server.rs가 citations·keywords·metadata 등 파싱)
• Python outbound.proto의 잘못된 LinkMetadata·ImageMetadata는 폐기 후 정본에 맞춤
• ProtobufAdapter.to_link_metadata: 재생성 후 citations 필드 채우기 (도메인 모델에 이미 존재)
• ImageMetadata / to_image_metadata / BatchItemResult.image_metadata는 정본에 없으면 제거하거나 이미지 배치를 별도 이슈로 분리

작업 체크리스트

• packages/grpc-proto/에 inbound.proto·outbound.proto 추가 (위 합의 반영)
• api-server/build.rs를 ../grpc-proto 참조로 변경; packages/api-server/proto/ 제거 및 문서 갱신 (docs/references/grpc-contracts.md)
• ai-server용 protoc 래퍼 스크립트 추가, pb2 재생성, src/grpc/proto/inbound/inbound/ 등 중복 산출물 삭제
• ProtobufAdapter 및 outbound 사용처 수정, dead code 정리
• cargo clippy / cargo test --lib, pytest(gRPC 관련)로 검증

문서·운영

• proto 변경 순서: packages/grpc-proto 편집 → Rust 빌드 확인 → Python 생성 스크립트 실행 → 커밋
• (선택) pre-push에서 grpc-proto 변경 시 pb2 미갱신 경고
• (선택) buf.yaml + buf lint

리스크·배포

• outbound 정본 통합 시 한 PR에서 Python 어댑터·테스트까지 수정 필요
• 배포: 콜백은 AI → API 이므로 API를 먼저 새 proto에 맞게 배포한 뒤 AI를 배포하는 순서가 안전

참고 경로

구분	파일
Rust 빌드	packages/api-server/build.rs
Rust 클라이언트	packages/api-server/src/services/decoded_ai_grpc/client.rs
Rust 콜백 서버	packages/api-server/src/services/backend_grpc/server.rs
Python servicer	packages/ai-server/src/grpc/servicer/metadata_servicer.py
Python 어댑터	packages/ai-server/src/adapters/protobuf_adapter.py
현재 정본(이관 전)	packages/api-server/proto/, packages/ai-server/src/grpc/proto/

[thxforall]

✅ 구현 완료 확인. packages/api-server/proto/ai.proto가 단일 소스, packages/ai-server/src/grpc/proto/inbound/에 Python 생성 파일. OG 추출, 링크 분석, 이미지 분석, 포스트 에디토리얼 메시지 정의 공유.