pkg/grpc -- gRPC Server Wrapper

Design Philosophy

pkg/server -> HTTP/1.1 + HTTP/2 + HTTP/3 (REST + WebSocket) :8080
pkg/grpc -> gRPC Server :9090
Both share:
 app/models/ <- Data structures
 app/services/ <- Business logic
 pkg/errors/ <- Error Catalog
 pkg/hidb/ <- Database
 pkg/logger/ <- Logging
 pkg/config/ <- Configuration

Quick Start

Create a gRPC Project

hyp new grpc userservice && cd userservice && go mod tidy
make proto # Compile .proto -> Go code
go run .

Add gRPC to an Existing Project

import (
 hypgrpc "github.com/maoxiaoyue/hypgo/pkg/grpc"
 "github.com/maoxiaoyue/hypgo/pkg/grpc/interceptor"
)
grpcSrv := hypgrpc.New(hypgrpc.Config{
 Addr: ":9090",
 EnableReflection: true,
 EnableHealthCheck: true,
}, logger,
 grpc.ChainUnaryInterceptor(
 interceptor.Recovery(logger),
 interceptor.Logger(logger),
 ),
)
// Register services
pb.RegisterUserServiceServer(grpcSrv.GRPCServer(), &UserServer{})
// Start
go grpcSrv.Start()
// Graceful shutdown
grpcSrv.GracefulStop()

Config

type Config struct {
 Addr string // Listen address (default ":9090")
 TLS *TLSConfig // TLS configuration (nil = plaintext)
 EnableReflection bool // Enable gRPC reflection (grpcurl debugging)
 EnableHealthCheck bool // Enable gRPC health check service
 MaxRecvMsgSize int // Maximum receive message size (default 4MB)
 MaxSendMsgSize int // Maximum send message size (default 4MB)
}
type TLSConfig struct {
 CertFile string
 KeyFile string
}

Server API

Interceptors (gRPC Middleware)

Using Interceptors

s := hypgrpc.New(cfg, logger,
 grpc.ChainUnaryInterceptor(
 interceptor.Recovery(logger), // Outermost: catch panics
 interceptor.Logger(logger), // Log each RPC
 interceptor.Auth(myAuthFunc, // Validate token
 "/grpc.health.v1.Health/Check", // Skip health check
 ),
 interceptor.RateLimit(interceptor.RateLimitConfig{
 MaxRequests: 100, // 100 per minute
 Window: time.Minute,
 }),
 ),
)

Auth Interceptor Details

// Define validation function
authFn := func(ctx context.Context, token string) (interface{}, error) {
 // Validate JWT token
 claims, err := jwt.Validate(token)
 if err != nil {
 return nil, err // -> codes.Unauthenticated
 }
 return claims, nil // Stored in context
}
// Extract user in RPC handler
func (s *Server) GetUser(ctx context.Context, req *pb.GetUserReq) (*pb.UserResp, error) {
 user, ok := interceptor.UserFromContext(ctx)
 if !ok {
 return nil, status.Error(codes.Internal, "no user in context")
 }
 // user is the object returned by authFn
}

RateLimit Security Design

Project Structure

hyp new grpc userservice

userservice/
├── app/
│ ├── proto/userservicepb/
│ │ └── userservice.proto <- Protobuf definitions
│ ├── rpc/
│ │ └── userservice_server.go <- gRPC service implementation
│ ├── models/ <- Shared data structures
│ ├── services/ <- Shared business logic
│ └── config/config.yaml
├── main.go
├── Makefile <- make proto
└── go.mod

Adding More Services

hyp generate proto order
# -> app/proto/orderpb/order.proto
# -> app/rpc/order_server.go

Coexistence with REST

func main() {
 // REST Server
 srv := server.New(cfg, log)
 routers.Setup(srv.Router())
 // gRPC Server
 grpcSrv := hypgrpc.New(hypgrpc.Config{Addr: ":9090"}, log)
 pb.RegisterUserServiceServer(grpcSrv.GRPCServer(), &UserServer{})
 // Start both simultaneously
 go srv.Start() // :8080 REST
 go grpcSrv.Start() // :9090 gRPC
 // Graceful shutdown
 quit := make(chan os.Signal, 1)
 signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
 <-quit
 srv.Shutdown(ctx)
 grpcSrv.GracefulStop()
}

Shared Service Layer

Controller (REST) -+
 +-> UserService (app/services/) -> Database
RPC Handler (gRPC) -+

Security

Required Tools

# protoc compiler
# https://github.com/protocolbuffers/protobuf/releases
# Go protobuf plugins
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
# Debugging tool (optional)
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest