2nd/10_Wiki/Topics/Architecture/gRPC_and_Protocol_Buffers.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-grpc-and-protocol-buffers	gRPC and Protocol Buffers	10_Wiki/Topics	verified	self	gRPC Protobuf protocol-buffers	none	A	0.95	applied	rpc networking protobuf microservices http2		2026-05-10	pending	language framework Multi (Go, Rust, TS, Python) gRPC + Protobuf 3 / Edition 2024

gRPC and Protocol Buffers

매 한 줄

"매 schema-first IDL + HTTP/2 RPC + binary serialization 의 stack.". Protocol Buffers 는 2008 Google 공개, gRPC 는 2015 OSS — 매 internal Stubby 의 successor. 매 2026 microservice / cross-language API 의 매 default — 매 REST+JSON 보다 5-10× compact, 매 streaming 매 native, 매 contract 강제.

매 핵심

매 Protocol Buffers

• Schema: .proto file — 매 message + service 정의.
• Wire format: tag-length-value, varint encoding — 매 forward/backward compat (unknown field 보존).
• Edition 2024: proto2 / proto3 의 통합 — 매 explicit feature flag.
• Compiler: protoc + plugin (go, ts-proto, prost, python-betterproto).

매 gRPC

• Transport: HTTP/2 — 매 multiplexing, header compression (HPACK).
• 4 RPC types: unary, server-stream, client-stream, bidi-stream.
• Status codes: 매 OK, INVALID_ARGUMENT, UNAUTHENTICATED, DEADLINE_EXCEEDED (16개 표준).
• Deadline: 매 client → server propagate. 매 RPC chain 매 cumulative.
• Metadata: 매 trailer/header — auth token, trace.
• gRPC-Web: 매 browser support (HTTP/1.1 fallback proxy).
• Connect / gRPC-Gateway: 매 REST+gRPC dual.

매 응용

1. Microservice internal RPC.
2. Mobile ↔ backend (Square, Netflix).
3. Service mesh (Envoy, Istio).
4. Streaming (live ML inference, IoT).

💻 패턴

.proto schema

edition = "2024";

package shop.v1;

option go_package = "github.com/example/shop/v1;shopv1";

service Catalog {
  rpc GetProduct(GetProductRequest) returns (Product);
  rpc StreamUpdates(StreamUpdatesRequest) returns (stream ProductUpdate);
  rpc UploadImages(stream Image) returns (UploadAck);
  rpc Chat(stream ChatMsg) returns (stream ChatMsg);
}

message GetProductRequest {
  string id = 1;
}

message Product {
  string id = 1;
  string name = 2;
  int64 price_cents = 3;
  repeated string tags = 4;
  google.protobuf.Timestamp updated_at = 5;
}

Go server (unary + stream)

type catalogServer struct{ shopv1.UnimplementedCatalogServer }

func (s *catalogServer) GetProduct(ctx context.Context, req *shopv1.GetProductRequest) (*shopv1.Product, error) {
    if req.Id == "" {
        return nil, status.Error(codes.InvalidArgument, "id required")
    }
    p, err := s.db.Find(ctx, req.Id)
    if errors.Is(err, sql.ErrNoRows) {
        return nil, status.Error(codes.NotFound, "product missing")
    }
    return p, err
}

func (s *catalogServer) StreamUpdates(req *shopv1.StreamUpdatesRequest, srv shopv1.Catalog_StreamUpdatesServer) error {
    for ev := range s.bus.Subscribe(srv.Context()) {
        if err := srv.Send(ev); err != nil { return err }
    }
    return nil
}

TS client (ts-proto + grpc-js)

import { credentials } from '@grpc/grpc-js';
import { CatalogClient } from './gen/shop/v1/catalog';

const client = new CatalogClient('catalog:50051', credentials.createSsl());

const p = await client.getProduct({ id: 'sku-42' }, { deadline: Date.now() + 1000 });
console.log(p.name);

// streaming
const stream = client.streamUpdates({});
stream.on('data', (u) => console.log('update', u));
stream.on('error', (e) => console.error(e));

Deadline propagation

ctx, cancel := context.WithTimeout(ctx, 500*time.Millisecond)
defer cancel()
// 매 outgoing RPC 매 자동 deadline 전달.
resp, err := downstream.Sub(ctx, req)

Interceptor (auth + tracing)

func authUnary(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
    md, _ := metadata.FromIncomingContext(ctx)
    tok := md.Get("authorization")
    if len(tok) == 0 { return nil, status.Error(codes.Unauthenticated, "no token") }
    user, err := verify(tok[0])
    if err != nil { return nil, status.Error(codes.Unauthenticated, "bad token") }
    return handler(context.WithValue(ctx, userKey{}, user), req)
}

s := grpc.NewServer(grpc.UnaryInterceptor(authUnary))

gRPC-Web (browser)

import { createPromiseClient } from '@connectrpc/connect';
import { createGrpcWebTransport } from '@connectrpc/connect-web';
import { Catalog } from './gen/shop/v1/catalog_connect';

const transport = createGrpcWebTransport({ baseUrl: 'https://api.example.com' });
const client = createPromiseClient(Catalog, transport);
const p = await client.getProduct({ id: 'sku-42' });

Buf for build + lint

# buf.yaml
version: v2
modules:
  - path: proto
lint:
  use: [DEFAULT]
breaking:
  use: [FILE]

buf lint
buf breaking --against '.git#branch=main'
buf generate

Backward-compat 규칙

message Product {
  string id = 1;
  string name = 2;
  // 매 deprecated 후에도 number 재사용 X
  reserved 3;
  reserved "old_price";
  int64 price_cents = 4;
}

매 결정 기준

상황	Approach
매 internal microservice	gRPC unary + interceptor
매 browser client	Connect / gRPC-Web
매 public open API	REST/JSON or gRPC-Gateway dual
매 streaming (logs, ML)	server-stream / bidi
매 mobile (cellular flaky)	gRPC + retry interceptor + deadline

기본값: 매 internal = gRPC, 매 external = Connect (dual REST + gRPC).

🔗 Graph

• 변형: Connect_RPC
• 응용: Service Mesh · Microservices · Envoy
• Adjacent: Buf · OpenAPI

🤖 LLM 활용

언제: 매 cross-language API, 매 streaming, 매 strict contract. 언제 X: 매 simple browser CRUD (REST 충분), 매 ad-hoc tooling (JSON 직관적).

❌ 안티패턴

• Field number 재사용: 매 wire-incompatible — 매 reserved 의 사용.
• 매 required 다용: 매 schema evolution 차단 — proto3 default optional 유지.
• 매 deadline 미설정: 매 server cascade hang.
• 매 large message (>4MB): 매 default limit hit — 매 stream 으로 분할.
• 매 .proto 의 versioning X: 매 v1, v2 package 분리 mandatory.

🧪 검증 / 중복

• Verified (grpc.io docs, protobuf.dev Edition 2024 spec, Buf docs).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — gRPC patterns, Edition 2024, Connect-RPC