gRPC First Server and Client
This topic walks through building a complete, working gRPC server and client in Go. By the end you will have two programs that talk to each other using a proto-defined contract. The service calculates the area of geometric shapes — simple enough to focus on the gRPC mechanics, not the business logic.
Project Structure
shape-service/ ├── proto/ │ └── shape.proto ← contract definition ├── server/ │ └── main.go ← server implementation ├── client/ │ └── main.go ← client that calls the server ├── gen/ │ └── shape/ │ ├── shape.pb.go ← generated message code (auto) │ └── shape_grpc.pb.go ← generated service code (auto) └── go.mod
Step 1: Write the Proto File
// proto/shape.proto
syntax = "proto3";
package shape;
option go_package = "./gen/shape";
// The request carries the shape type and its dimensions
message ShapeRequest {
string shape_type = 1; // "circle", "rectangle", "triangle"
double dimension1 = 2; // radius for circle, width for rectangle/triangle
double dimension2 = 3; // unused for circle, height for rectangle/triangle
double dimension3 = 4; // unused for circle/rectangle, base for triangle
}
// The response carries the calculated area
message ShapeResponse {
double area = 1;
string shape_type = 2;
string formula = 3; // human-readable formula used
}
// The service exposes one unary method
service ShapeService {
rpc CalculateArea (ShapeRequest) returns (ShapeResponse);
}
Step 2: Generate Code from the Proto File
Install the compiler and plugins (one-time setup):
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
Run the generator:
protoc \
--go_out=. \
--go_opt=paths=source_relative \
--go-grpc_out=. \
--go-grpc_opt=paths=source_relative \
proto/shape.proto
What gets created:
gen/shape/shape.pb.go ← ShapeRequest and ShapeResponse structs
gen/shape/shape_grpc.pb.go ← ShapeServiceClient and ShapeServiceServer interfaces
Step 3: Implement the Server
// server/main.go
package main
import (
"context"
"fmt"
"log"
"math"
"net"
pb "shape-service/gen/shape"
"google.golang.org/grpc"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
)
// shapeServer embeds the generated unimplemented base
type shapeServer struct {
pb.UnimplementedShapeServiceServer
}
// CalculateArea is our actual business logic
func (s *shapeServer) CalculateArea(
ctx context.Context,
req *pb.ShapeRequest) (*pb.ShapeResponse, error) {
switch req.ShapeType {
case "circle":
r := req.Dimension1
area := math.Pi * r * r
return &pb.ShapeResponse{
Area: area,
ShapeType: "circle",
Formula: fmt.Sprintf("π × %.2f² = %.4f", r, area),
}, nil
case "rectangle":
w, h := req.Dimension1, req.Dimension2
area := w * h
return &pb.ShapeResponse{
Area: area,
ShapeType: "rectangle",
Formula: fmt.Sprintf("%.2f × %.2f = %.4f", w, h, area),
}, nil
case "triangle":
b, h := req.Dimension1, req.Dimension2
area := 0.5 * b * h
return &pb.ShapeResponse{
Area: area,
ShapeType: "triangle",
Formula: fmt.Sprintf("0.5 × %.2f × %.2f = %.4f", b, h, area),
}, nil
default:
// Return a proper gRPC error — not a panic or a log.Fatal
return nil, status.Errorf(codes.InvalidArgument,
"unknown shape type: %s", req.ShapeType)
}
}
func main() {
// 1. Listen on a TCP port
lis, err := net.Listen("tcp", ":50051")
if err != nil {
log.Fatalf("failed to listen: %v", err)
}
// 2. Create the gRPC server
grpcServer := grpc.NewServer()
// 3. Register our implementation with the gRPC server
pb.RegisterShapeServiceServer(grpcServer, &shapeServer{})
// 4. Start serving
log.Println("ShapeService listening on :50051")
if err := grpcServer.Serve(lis); err != nil {
log.Fatalf("failed to serve: %v", err)
}
}
Step 4: Write the Client
// client/main.go
package main
import (
"context"
"fmt"
"log"
"time"
pb "shape-service/gen/shape"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials/insecure"
)
func main() {
// 1. Open a channel to the server
conn, err := grpc.NewClient(
"localhost:50051",
grpc.WithTransportCredentials(insecure.NewCredentials()),
)
if err != nil {
log.Fatalf("connection failed: %v", err)
}
defer conn.Close()
// 2. Create the stub
client := pb.NewShapeServiceClient(conn)
// 3. Set a deadline — if the server takes longer than 5s, cancel the call
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
// 4. Call the server — feels like a local function call
shapes := []struct {
shapeType string
d1, d2, d3 float64
}{
{"circle", 5, 0, 0},
{"rectangle", 4, 6, 0},
{"triangle", 3, 8, 0},
{"hexagon", 2, 0, 0}, // will trigger an error
}
for _, s := range shapes {
resp, err := client.CalculateArea(ctx, &pb.ShapeRequest{
ShapeType: s.shapeType,
Dimension1: s.d1,
Dimension2: s.d2,
Dimension3: s.d3,
})
if err != nil {
fmt.Printf("Error for %s: %v\n", s.shapeType, err)
continue
}
fmt.Printf("Shape: %-12s Area: %8.4f Formula: %s\n",
resp.ShapeType, resp.Area, resp.Formula)
}
}
Step 5: Run and Test
Terminal 1 — start the server:
cd server
go run main.go
Output: ShapeService listening on :50051
Terminal 2 — run the client:
cd client
go run main.go
Expected output:
Shape: circle Area: 78.5398 Formula: π × 5.00² = 78.5398
Shape: rectangle Area: 24.0000 Formula: 4.00 × 6.00 = 24.0000
Shape: triangle Area: 12.0000 Formula: 0.5 × 3.00 × 8.00 = 12.0000
Error for hexagon: rpc error: code = InvalidArgument
desc = unknown shape type: hexagon
What Happens Under the Hood
When client.CalculateArea(ctx, req) runs:
Client gRPC Library Server
──────────────────────────────────────────────────────────────────
1. Serialise req to protobuf bytes
2. Open HTTP/2 stream on channel
3. Send HEADERS frame ─────────────────►
:path = /shape.ShapeService/CalculateArea
content-type = application/grpc
4. Send DATA frame (proto bytes) ─────────────────►
5. Deserialise bytes → ShapeRequest
6. Call CalculateArea method
7. Serialise response to bytes
◄─────────────────
8. Receive HEADERS frame (status)
9. Receive DATA frame (proto bytes)
10. Deserialise bytes → ShapeResponse
11. Return to application code
go.mod Dependencies
module shape-service go 1.22 require ( google.golang.org/grpc v1.64.0 google.golang.org/protobuf v1.34.1 )
Summary
Building a gRPC service in Go takes five steps: write the proto file, generate code with protoc, implement the server by satisfying the generated interface, write a client that creates a channel and a stub, and call the server methods. The business logic lives only in the server method implementation — everything else is generated or provided by the gRPC library.