gRPC-Web에서 connect-web으로 마이그레이션

바른의 웹 클라이언트는 기존 gRPC-Web에서 connect-web으로 옮겨갔습니다. connect-web은 브라우저에서 별도 프록시 없이 바른 서버를 직접 호출할 수 있게 해주는 가벼운 RPC 클라이언트입니다.

이 문서는 웹 프런트엔드를 gRPC-Web에서 connect-web으로 옮길 때의 변경점을 정리합니다.

왜 옮기나요

바른 서버는 connect-go로 구현되어 있어 Connect-RPC·gRPC·REST를 동시에 받습니다. 브라우저에서는 @connectrpc/connect·@connectrpc/connect-web과 @bufbuild/protobuf를 조합해, 표준 fetch 기반으로 깔끔하게 호출할 수 있습니다.

패키지 교체

# 이전(gRPC-Web) 의존성을 걷어내고
npm remove grpc-web google-protobuf

# connect-web 스택을 설치합니다.
npm install @connectrpc/connect @connectrpc/connect-web @bufbuild/protobuf

클라이언트 코드 비교

import { createConnectTransport } from "@connectrpc/connect-web";
import { createClient } from "@connectrpc/connect";
import { LanguageService } from "./gen/language_service_connect";

// 바른 서버로의 전송 계층을 만듭니다.
const transport = createConnectTransport({
  baseUrl: "https://api.bareun.ai",
});
const client = createClient(LanguageService, transport);

// AnalyzeSyntax 호출
const res = await client.analyzeSyntax({
  document: { content: "오늘 날씨가 좋네요.", language: "ko_KR" },
  encodingType: "UTF16",
});

import { LanguageServiceClient } from "./gen/Language_serviceServiceClientPb";
import { AnalyzeSyntaxRequest, Document } from "./gen/language_service_pb";

const client = new LanguageServiceClient("https://...:5656");
const req = new AnalyzeSyntaxRequest();
const doc = new Document();
doc.setContent("오늘 날씨가 좋네요.");
doc.setLanguage("ko_KR");
req.setDocument(doc);
client.analyzeSyntax(req, {}, (err, res) => { /* ... */ });

마이그레이션 체크리스트

• grpc-web·google-protobuf 제거, connect-web 3종 설치
• proto 코드 생성을 buf 기반 connect 플러그인으로 전환
• 클라이언트 생성 코드를 createConnectTransport + createClient로 교체
• 엔드포인트 정리: connect-web은 별도 Envoy 프록시 없이 바른 서버를 직접 호출
• 요청 필드명 확인(document, encodingType, customDictNames 등)

자주 묻는 질문

Q. connect-web으로 바꾸면 서버도 바꿔야 하나요?

아닙니다. 바른 서버는 connect-go로 구현되어 있어 connect-web 요청을 그대로 받습니다. 같은 LanguageService를 호출하므로 서버 변경 없이 클라이언트만 교체하면 됩니다.

Q. connect-web에서 쓰는 패키지는 무엇인가요?

@connectrpc/connect, @connectrpc/connect-web, 그리고 메시지 직렬화를 위한 @bufbuild/protobuf를 사용합니다. 기존 grpc-web·google-protobuf는 제거합니다.

Q. 분석 결과 구조도 달라지나요?

응답 메시지 구조(문장·어절·형태소, TextSpan 위치)는 동일합니다. 달라지는 것은 전송 방식과 클라이언트 코드이며, 분석 결과 자체는 같습니다.