GUIDES

gRPC Client, Server, and Gateway in Go

A Go gRPC example implementing a simple in-memory key-value store with three components: a gRPC server, a REST-to-gRPC gateway, and a CLI client.

Source: github.com/jecklgamis/go-grpc-example

Features

  • gRPC server with Put and Get operations backed by an in-memory store
  • REST gateway via grpc-gateway that proxies HTTP to gRPC
  • CLI client supporting both plain and TLS connections
  • Protobuf-defined API with auto-generated Go stubs
  • Docker image bundling all three binaries under supervisord

Architecture

cmd/
  server/   → gRPC server entry point (port 4000)
  gateway/  → REST-to-gRPC proxy entry point (port 8080)
  client/   → CLI client entry point
pkg/
  kvstore/  → kvstore.proto + generated stubs (*.pb.go, *.pb.gw.go)
  server/   → in-memory map store implementation
  gateway/  → grpc-gateway reverse proxy
  client/   → gRPC client wrapper
  version/  → build version injected via ldflags

Data flow: REST clients → gateway (:8080) → gRPC server (:4000). gRPC clients connect to the server directly.

Requirements

  • Go 1.26+
  • protoc (Protocol Buffers compiler)
brew install protobuf
protoc --version  # should be 3.x or above

Getting Started

# Install protoc Go plugins
make install-deps

# Regenerate protobuf stubs and build all binaries
make build

This produces native and linux/amd64 binaries under bin/:

bin/server          bin/server-linux-amd64
bin/gateway         bin/gateway-linux-amd64
bin/client          bin/client-linux-amd64

Running Locally

Start the gRPC server:

bin/server -port 4000
# 2019/08/13 07:30:24 Started server on port 4000

Start the REST gateway (in a separate terminal):

bin/gateway -port 8080 -grpcServerAddr localhost:4000
# 2019/08/13 08:27:25 Started gateway on port 8080

Use the CLI client:

bin/client -serverAddr localhost:4000 put some-key some-value
bin/client -serverAddr localhost:4000 get some-key

# With TLS (uses InsecureSkipVerify — testing only)
bin/client -serverAddr localhost:4000 -ssl put some-key some-value

REST API (via Gateway)

PUT a key-value pair:

curl -X PUT http://localhost:8080/v1 \
  -d '{"key": "some-key", "value": "some-value"}'

GET a value by key:

curl "http://localhost:8080/v1?key=some-key"

HTTP routing rules are defined in pkg/kvstore/kvstore.yaml, not as proto annotations.

Docker

# Build image (requires binaries already built)
make image

# Run container (exposes ports 4000 and 8080)
make run

# Open a shell in the container
make run-bash

Or pull directly:

docker run -p 4000:4000 -p 8080:8080 -it jecklgamis/go-grpc-example:main

Proto Definition

The API is defined in pkg/kvstore/kvstore.proto. After any changes, regenerate stubs with:

make protobufs          # generates kvstore.pb.go and kvstore_grpc.pb.go
make gateway-protobufs  # generates kvstore.pb.gw.go

Do not edit the generated *.pb.go / *.pb.gw.go files directly.

Source

Full source code available on GitHub: jecklgamis/go-grpc-example