Belajar gRPC - gRPC-Web, Envoy, dan Gateway Integrations

#Pendahuluan

Di episode 1 kita menyebutkan: gRPC bukan untuk browser langsung. Tapi bagaimana kalau frontend harus bicara dengan service gRPC? Jawabannya bukan meninggalkan gRPC, melainkan menyediakan jembatan. Episode 16 membahas tiga jembatan itu: gRPC-Web (protokol browser), Envoy (proxy yang menerjemahkan), dan grpc-gateway (REST gateway untuk API hybrid).

Kalian akan memahami mengapa browser tidak bisa memakai gRPC mentah, bagaimana Envoy menjembatani, dan bagaimana satu service .proto melayani konsumen gRPC, gRPC-Web, dan REST sekaligus.

#Konsep gRPC-Web

#Kenapa Browser Tidak Bisa Memakai gRPC Langsung

Browser tidak bisa memakai gRPC mentah karena dua batasan: JavaScript tidak bisa mengendalikan flag HTTP/2 (seperti trailer header) yang dibutuhkan gRPC, dan streaming response di sisi client tidak didukung penuh. gRPC-Web adalah protokol yang memecahkan ini — versi gRPC yang bekerja di browser via XHR atau fetch biasa.

Konsekuensi praktisnya: unary didukung penuh, server streaming bekerja (tapi sebagai satu response kumpulan), sedangkan client streaming dan bidirectional streaming tidak tersedia di gRPC-Web. Desain frontend harus menyesuaikan.

#Client gRPC-Web di Browser

Dengan @grpc/grpc-js dan @grpc/proto-loader, client browser cukup memakai service yang sama:

Client gRPC-Web

import { GrpcWebFetchTransport } from "@protobuf-ts/grpcweb-transport";
 
const transport = new GrpcWebFetchTransport({
  baseUrl: "https://api.example.com",
});
 
const client = new ProductServiceClient(transport);
const res = await client.getProduct({ id: "p-001" });
console.log(res.response.name);

new GrpcWebFetchTransport({ baseUrl }) membuat transport gRPC-Web yang berjalan di atas fetch browser. Perhatikan: client di atas tidak membuka koneksi langsung ke server — traffic tetap lewat proxy.

#Envoy Proxy

#Envoy sebagai Jembatan

Envoy adalah proxy tingkat produksi yang memahami gRPC. Browser mengirim gRPC-Web ke Envoy, dan Envoy menerjemahkannya menjadi gRPC HTTP/2 penuh ke server. Konfigurasi Envoy memakai protokol kontrol xDS (episode 10) atau file bootstrap statis:

static_resources:
  listeners:
    - name: grpc_web_listener
      address:
        socket_address:
          address: 0.0.0.0
          port_value: 8080
      filter_chains:
        - filters:
            - name: envoy.filters.network.http_connection_manager
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
                codec_type: AUTO
                http_filters:
                  - name: envoy.filters.http.grpc_web
                    typed_config:
                      "@type": type.googleapis.com/envoy.extensions.filters.http.grpc_web.v3.GrpcWeb
                  - name: envoy.filters.http.router
                    typed_config:
                      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
                route_config:
                  virtual_hosts:
                    - name: grpc_service
                      domains: ["*"]
                      routes:
                        - match:
                            prefix: /
                          route:
                            cluster: catalog_grpc

Konfigurasi YAML di atas mendeklarasikan listener di port 8080, filter grpc_web yang menerjemahkan protokol, dan rute ke cluster catalog_grpc. Struktur route_config ini menentukan bahwa semua path menuju service gRPC backend.

#Cluster Envoy

Tambahkan definisi cluster untuk mengarahkan Envoy ke server gRPC:

clusters:
  - name: catalog_grpc
    connect_timeout: 1s
    type: STRICT_DNS
    lb_policy: ROUND_ROBIN
    http2_protocol_options: {}
    load_assignment:
      cluster_name: catalog_grpc
      endpoints:
        - lb_endpoints:
            - endpoint:
                address:
                  socket_address:
                    address: catalog
                    port_value: 50051

http2_protocol_options: {} memberitahu Envoy memakai HTTP/2 ke backend, dan lb_policy: ROUND_ROBIN mendistribusikan traffic antar instance. Envoy kini menjadi satu pintu masuk untuk browser dan client gRPC-Web.

#REST Gateway dengan grpc-gateway

#Membangkitkan REST dari .proto

grpc-gateway membangkitkan proxy REST dari file .proto yang sama, dengan tambahan annotation google.api.http:

import "google/api/annotations.proto";
 
service CatalogService {
  rpc GetProduct(ProductId) returns (Product) {
    option (google.api.http) = {
      get: "/v1/products/{id}"
    };
  }
}

Dengan option (google.api.http), method unary GetProduct juga tersedia sebagai GET /v1/products/{id}. Satu kontrak menghasilkan dua transport: gRPC untuk service internal, REST untuk konsumen publik.

#Generate dan Jalankan

go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
protoc -I . \
  --grpc-gateway_out=. \
  --grpc-gateway_opt=paths=source_relative \
  proto/catalog/v1/product.proto

protoc --grpc-gateway_out=. membangkitkan proxy yang menerima HTTP/JSON dan memanggil backend gRPC. Proxy ini memakai service yang sama sehingga tidak ada logika ganda.

#Hybrid API dalam Satu Arsitektur

#Menyatukan Semua Jalur

Arsitektur hibrida yang umum: konsumen internal memakai gRPC langsung, browser memakai gRPC-Web via Envoy, dan partner eksternal memakai REST via grpc-gateway. Semua jalur berakhir di server gRPC yang sama:

Browser  ->  Envoy  ->  gRPC server
Partner   ->  grpc-gateway  ->  gRPC server
Microservice ->  gRPC  ->  gRPC server

Keuntungannya jelas: satu kontrak .proto, satu implementasi, tiga konsumen. Konsistensi API terjaga karena gateway hanyalah penerjemah, bukan implementasi ulang. Diagram di atas menunjukkan bagaimana gRPC server menjadi satu sumber kebenaran untuk semua jalur.

#Penutup

Inti yang harus dibawa pulang:

• Browser tidak bisa memakai gRPC mentah; gRPC-Web menyediakan protokol untuk frontend.
• Unary dan server streaming didukung gRPC-Web; client dan bidirectional streaming tidak.
• Envoy menerjemahkan gRPC-Web ke gRPC HTTP/2 penuh di backend.
• grpc-gateway membangkitkan REST dari annotation google.api.http di .proto.
• Satu kontrak bisa melayani gRPC, gRPC-Web, dan REST secara bersamaan.
• Envoy juga menjadi gerbang menuju service mesh dan observability terpusat.

Di episode 17 selanjutnya kita membahas CI/CD, GitOps, dan production deployment — pipeline build untuk kompilasi .proto, code generation, dan linting, validasi kontrak dengan automated protobuf tests, serta deployment GitOps untuk service gRPC di Kubernetes. Arsitektur yang lengkap kini harus dibangun, diuji, dan dideploy secara otomatis.