프로젝트 소개

grpc-web은 브라우저 클라이언트를 위한 gRPC의 JavaScript 구현으로, grpc/grpc-web 저장소에서 유지 관리됩니다. 브라우저는 원시 HTTP/2 gRPC 연결을 열 수 없기 때문에 gRPC-web 클라이언트는 특수 프록시를 통해 gRPC 서비스와 통신합니다. Envoy가 기본 프록시이며, 이 프로젝트는 gRPC-web Go 프록시, Apache APISIX, Nginx의 gRPC 모듈과의 상호 운용성도 문서화합니다. 이 프로젝트는 두 가지 주요 구성 요소를 제공합니다. 첫째, npm에 `grpc-web`으로 게시된 런타임 라이브러리로, 현재 전적으로 TypeScript로 작성되어 일급 타입 안전성, 런타임 의존성 제로, 내장 타입 정의를 제공합니다. 둘째, `.proto` 정의로부터 클라이언트 서비스 스텁을 생성하는 protoc 플러그인 `protoc-gen-grpc-web`입니다. 생성은 일반적으로 표준 `--js_out` 플러그인(protobuf 메시지 클래스용)과 `--grpc-web_out`(서비스 스텁용)을 함께 사용하며, Browserify, Webpack 또는 Closure Compiler로 번들링할 수 있습니다. 지원되는 RPC 모드는 단항 호출과 서버 측 스트리입니다. 서버 측 스트리밍은 페이로드가 base64로 인코딩되어 `Content-Type: application/grpc-web-text`로 전송되는 `grpcwebtext` 이어 포맷 모드에서만 사용할 수 있습니다. 바이너리 모드인 `grpcweb`은 바이너리 protobuf 페이로드와 함께 `Content-Type: application/grpc-web+proto`를 사용하지만 단항 호출만 지원합니다. 클라이언트 측 및 양방향 스트리밍은 현재 지원되지 않습니다. 코드 생성은 여러 가지 임포트 스타일을 제공합니다. `closure`(기본값, `goog.require()` 사용), `commonjs`(`require()` 사용), `commonjs+dts`(CommonJS 스텁과 `.d.ts` 타입 정의 파일), `typescript`(전체 TypeScript 출력)입니다. `commonjs+dts`와 `typescript` 스타일은 `--js_out`이 아닌 `--grpc-web_out`에서만 지원됩니다. README에는 바이너리 와이어 포맷으로 TypeScript 코드를 생성하는 구체적인 예제가 포함되어 있으며, 이는 TypeScript 서비스 클라이언트, JavaScript protobuf 모듈, 그리고 일치하는 `.d.ts` 정의 파일을 생성합니다. 클라이언트 사용법은 간단합니다. 프록시 URL로 서비스 클라이언트를 인스턴스화하고, 요청 메시지를 작성한 다음, 선택적 메타데이터와 백을 사용하여 RPC를 호출합니다. 서버 측 스트리밍은 `data`, `status`, `end` 이벤트와 `cancel()` 메서드가 있는 스트림 객체를 반환합니다. 리초 단위의 Unix 타임스탬프를 포함하는 `deadline` 헤더를 전달하여 데드라인을 설정할 수 있습니다. 두 가지 클라이언트 스타일을 사용할 수 있습니다. 콜백 기반 클라이언트와 Promise 기반 클라이언트이지만, Promise 변형은 메타데이터와 상태에 대한 `.on(...)` 백에 접근할 수 없습니다. 인증 및 재시도와 같은 기능을 위해 사용자 정의 인터셉터를 구현하고 체인으로 연결할 수 있습니다. 두 가지 인터셉터 유형이 있습니다. 단항 RPC를 가로채며 Promise 클라이언트에서만 사용할 수 있는 `UnaryInterceptor`와, 더 다재다능하며 일반 클라이언트에서 작동하는 `StreamInterceptor`입니다. 저장소에는 프로토콜 버퍼로 서비스를 정의하고, Node.js gRPC 서비스를 구현하고, Envoy 프록시를 구성하고, protobuf 클래스와 클라이언트 스을 생성하고, JS 의존성을 정적 라이브러리로 컴파일하는 과정을 안내하는 Hello World 예제가 포함되어 있습니다. 더 고급 Echo 데모는 Docker Compose로 실행할 수 있으며 스트리밍 테스트를 위한 브라우저 페이지를 제공합니다. README는 또한 gRPC-web 지원이 있는 Armeria(JVM) 및 Tonic(Rust) 서버 프레임워크와 Vite 호환성 데모를 포함한 생태계 통합을 언급합니다. 로드맵 문서는 Python, Java, Node에 대한 언어별 웹 프레임워크 지원을 포함한 향후 작업을 설명합니다.