protoc --version
# libprotoc 25.x or later

pip install grpcio grpcio-tools grpcio-health-checking

mkdir -p python/gen

# Generate Python protobuf + gRPC stubs for both proto files.
#
# Flags explained:
#   -I.                    — Add the project root to the proto import path
#                            (so "import proto/common.proto" in service.proto resolves)
#   --python_out=python/gen — Where to write the *_pb2.py files (message classes)
#   --grpc_python_out=python/gen — Where to write the *_pb2_grpc.py files (service stubs)

python -m grpc_tools.protoc \
    -I. \
    --python_out=python/gen \
    --grpc_python_out=python/gen \
    proto/common.proto \
    proto/service.proto

import proto.common_pb2 as common__pb2

touch python/gen/__init__.py

import sys
import os
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "gen"))

python -c "from python.gen import service_pb2, service_pb2_grpc; print('Python codegen OK')"

# The Go protobuf plugin (generates *.pb.go — message types)
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

# The Go gRPC plugin (generates *_grpc.pb.go — service stubs)
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

export PATH="$PATH:$(go env GOPATH)/bin"

cd go/

# WHY this module path?  It matches the go_package option in service.proto.
# The generated code will import common.pb.go using this module path.
go mod init github.com/example/grpc-templates

# Add gRPC dependencies
go get google.golang.org/grpc
go get google.golang.org/protobuf
go get google.golang.org/grpc/health
go get google.golang.org/grpc/health/grpc_health_v1

cd ..

mkdir -p go/gen/catalogpb

protoc \
    -I. \
    --go_out=go/gen/catalogpb \
    --go_opt=paths=source_relative \
    --go-grpc_out=go/gen/catalogpb \
    --go-grpc_opt=paths=source_relative \
    proto/common.proto \
    proto/service.proto

cd go/ && go build ./... && echo "Go codegen OK" && cd ..

const protoLoader = require('@grpc/proto-loader');
const grpc = require('@grpc/grpc-js');

const packageDef = protoLoader.loadSync('proto/service.proto', {
    keepCase: true,           // Don't convert field names to camelCase
    longs: String,            // Represent int64 as strings (JS numbers lose precision at 2^53)
    enums: String,            // Represent enums as their string names
    defaults: true,           // Include default values for unset fields
    oneofs: true,             // Support oneof fields
    includeDirs: ['.'],       // Proto import search path
});

const proto = grpc.loadPackageDefinition(packageDef);
const catalog = proto.acme.catalog.v1;

cd node/
npm install @grpc/grpc-js @grpc/proto-loader
npm install --save-dev grpc-tools grpc_tools_node_protoc_ts
cd ..

mkdir -p node/gen

# Generate JavaScript stubs
npx grpc_tools_node_protoc \
    --js_out=import_style=commonjs,binary:node/gen \
    --grpc_out=grpc_js:node/gen \
    -I. \
    proto/common.proto \
    proto/service.proto

# Generate TypeScript type definitions
npx grpc_tools_node_protoc \
    --ts_out=grpc_js:node/gen \
    -I. \
    proto/common.proto \
    proto/service.proto

node -e "const pb = require('./node/gen/proto/service_pb'); console.log('Node codegen OK')"

PROTO_DIR := proto
PROTO_FILES := $(wildcard $(PROTO_DIR)/*.proto)

.PHONY: all python go node clean

all: python go node

python:
	@mkdir -p python/gen
	python -m grpc_tools.protoc \
		-I. \
		--python_out=python/gen \
		--grpc_python_out=python/gen \
		$(PROTO_FILES)
	@touch python/gen/__init__.py
	@echo "Python stubs generated in python/gen/"

go:
	@mkdir -p go/gen/catalogpb
	protoc \
		-I. \
		--go_out=go/gen/catalogpb \
		--go_opt=paths=source_relative \
		--go-grpc_out=go/gen/catalogpb \
		--go-grpc_opt=paths=source_relative \
		$(PROTO_FILES)
	@echo "Go stubs generated in go/gen/catalogpb/"

node:
	@mkdir -p node/gen
	npx grpc_tools_node_protoc \
		--js_out=import_style=commonjs,binary:node/gen \
		--grpc_out=grpc_js:node/gen \
		-I. \
		$(PROTO_FILES)
	@echo "Node stubs generated in node/gen/"

clean:
	rm -rf python/gen go/gen node/gen
	@echo "Generated code cleaned"

make all       # Generate for all languages
make python    # Generate Python only
make clean     # Remove all generated code

# macOS
brew install bufbuild/buf/buf

# Linux
curl -sSL "https://github.com/bufbuild/buf/releases/latest/download/buf-Linux-x86_64" -o /usr/local/bin/buf
chmod +x /usr/local/bin/buf

version: v2
modules:
  - path: proto
lint:
  use:
    - DEFAULT
breaking:
  use:
    - FILE

version: v2
plugins:
  # Python
  - remote: buf.build/protocolbuffers/python
    out: python/gen
  - remote: buf.build/grpc/python
    out: python/gen

  # Go
  - remote: buf.build/protocolbuffers/go
    out: go/gen/catalogpb
    opt: paths=source_relative
  - remote: buf.build/grpc/go
    out: go/gen/catalogpb
    opt: paths=source_relative

  # Node.js (use local plugin — Buf doesn't have an official remote plugin)
  - local: grpc_tools_node_protoc
    out: node/gen
    opt: grpc_js

# Lint your protos first (catches common mistakes)
buf lint

# Check for breaking changes against the previous version
buf breaking --against '.git#branch=main'

# Generate code for all languages
buf generate

make clean && make all

# Find where protoc's includes are installed
protoc --version  # Note the version
ls /usr/include/google/protobuf/  # Linux
ls /usr/local/include/google/protobuf/  # macOS (Homebrew)

# Pass the include path explicitly if needed
protoc -I. -I/usr/local/include ...

# These are the critical settings. See the full config in configs/.
clusters:
  - name: grpc_backend
    type: STRICT_DNS
    lb_policy: ROUND_ROBIN  # or LEAST_REQUEST for uneven workloads
    typed_extension_protocol_options:
      envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
        "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
        # WHY explicit_http_config instead of auto_config?
        # auto_config uses ALPN negotiation, which adds latency. Since we KNOW
        # the backends speak HTTP/2 (they're gRPC servers), we skip negotiation.
        explicit_http_config:
          http2_protocol_options:
            max_concurrent_streams: 100
    health_checks:
      - timeout: 2s
        interval: 10s
        unhealthy_threshold: 3
        healthy_threshold: 2
        grpc_health_check: {}  # Uses the standard gRPC health protocol

import grpc

# DNS-based: gRPC resolves the DNS name and round-robins across A records.
# WHY dns:///? The triple-slash tells gRPC to use its built-in DNS resolver
# instead of the OS resolver. This enables watching for DNS changes.
channel = grpc.insecure_channel(
    "dns:///catalog.example.com:50051",
    options=[
        # Pick the load balancing policy.
        ("grpc.lb_policy_name", "round_robin"),
        # How often to re-resolve DNS (milliseconds).
        ("grpc.dns_min_time_between_resolutions_ms", 10000),
    ],
)

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/balancer/roundrobin"
)

conn, err := grpc.Dial(
    "dns:///catalog.example.com:50051",
    grpc.WithDefaultServiceConfig(
        // The service config is JSON. This sets round_robin as the LB policy.
        `{"loadBalancingConfig": [{"round_robin":{}}]}`,
    ),
    grpc.WithTransportCredentials(insecure.NewCredentials()),
)

const grpc = require('@grpc/grpc-js');

// Node.js gRPC supports round_robin via channel options.
const client = new CatalogServiceClient(
    'dns:///catalog.example.com:50051',
    grpc.credentials.createInsecure(),
    {
        'grpc.lb_policy_name': 'round_robin',
        'grpc.service_config': JSON.stringify({
            loadBalancingConfig: [{ round_robin: {} }],
        }),
    }
);

apiVersion: v1
kind: Service
metadata:
  name: catalog-grpc
spec:
  clusterIP: None  # Headless — DNS returns pod IPs
  selector:
    app: catalog
  ports:
    - port: 50051
      targetPort: 50051

# Python — using grpc_health
from grpc_health.v1 import health_pb2, health_pb2_grpc, health

health_servicer = health.HealthServicer()
health_pb2_grpc.add_HealthServicer_to_server(health_servicer, server)

# Set status for the overall service
health_servicer.set("", health_pb2.HealthCheckResponse.SERVING)

# Set status for a specific service (optional)
health_servicer.set(
    "acme.catalog.v1.CatalogService",
    health_pb2.HealthCheckResponse.SERVING,
)

// Go — using grpc/health
import (
    "google.golang.org/grpc/health"
    healthpb "google.golang.org/grpc/health/grpc_health_v1"
)

healthServer := health.NewServer()
healthpb.RegisterHealthServer(grpcServer, healthServer)

// SERVING = ready to accept requests
healthServer.SetServingStatus("", healthpb.HealthCheckResponse_SERVING)
healthServer.SetServingStatus(
    "acme.catalog.v1.CatalogService",
    healthpb.HealthCheckResponse_SERVING,
)

# Python graceful shutdown
import signal

def shutdown(signum, frame):
    # Step 1: Mark unhealthy so LB stops sending traffic
    health_servicer.set("", health_pb2.HealthCheckResponse.NOT_SERVING)

    # Step 2: Grace period for in-flight RPCs
    # server.stop() returns an Event that fires when all RPCs complete
    # or the grace period expires — whichever comes first
    stopped = server.stop(grace=15)
    stopped.wait()

signal.signal(signal.SIGTERM, shutdown)

// Go graceful shutdown
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGTERM, syscall.SIGINT)
<-quit

// Step 1: Mark unhealthy
healthServer.SetServingStatus("", healthpb.HealthCheckResponse_NOT_SERVING)

// Step 2: GracefulStop waits for active RPCs to complete.
// Unlike Stop(), it doesn't forcefully kill connections.
grpcServer.GracefulStop()

# Python — keep-alive on server
server = grpc.server(
    futures.ThreadPoolExecutor(max_workers=10),
    options=[
        # Send pings every 60 seconds if no data is being sent.
        ("grpc.keepalive_time_ms", 60000),
        # Wait 20 seconds for a ping response before considering dead.
        ("grpc.keepalive_timeout_ms", 20000),
        # Allow pings even when there are no active RPCs.
        # WHY: Without this, idle connections are silently dropped by
        # firewalls, and the next RPC fails with a confusing error.
        ("grpc.keepalive_permit_without_calls", 1),
        # Allow clients to send pings every 30 seconds.
        # (Server enforces a minimum interval to prevent ping floods.)
        ("grpc.http2.min_ping_interval_without_data_ms", 30000),
    ],
)

# Limit to 100 concurrent streams per connection.
# WHY: With unlimited streams, one connection serves all RPCs,
# defeating client-side load balancing. With 100, the client
# opens new connections as load increases, and those connections
# are distributed across backends by the LB policy.
("grpc.max_concurrent_streams", 100)