{"id":29799869,"url":"https://github.com/muthu-kumar-u/go-grpc","last_synced_at":"2025-07-28T08:49:47.323Z","repository":{"id":306821363,"uuid":"1026211334","full_name":"muthu-kumar-u/go-grpc","owner":"muthu-kumar-u","description":"A minimal and clean gRPC boilerplate in Go designed to help you quickly start building scalable microservices. It includes service and proto structure, middleware hooks, error handling patterns, and logging—following clean architecture principles.","archived":false,"fork":false,"pushed_at":"2025-07-27T19:25:34.000Z","size":32,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-27T21:30:37.190Z","etag":null,"topics":["go-grpc","golang","grpc","protobuf","rpc","starter-kit","tls"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/muthu-kumar-u.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-25T13:48:31.000Z","updated_at":"2025-07-27T19:26:37.000Z","dependencies_parsed_at":"2025-07-27T21:30:47.736Z","dependency_job_id":null,"html_url":"https://github.com/muthu-kumar-u/go-grpc","commit_stats":null,"previous_names":["muthu-kumar-u/go-grpc"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/muthu-kumar-u/go-grpc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muthu-kumar-u%2Fgo-grpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muthu-kumar-u%2Fgo-grpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muthu-kumar-u%2Fgo-grpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muthu-kumar-u%2Fgo-grpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/muthu-kumar-u","download_url":"https://codeload.github.com/muthu-kumar-u/go-grpc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muthu-kumar-u%2Fgo-grpc/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267488818,"owners_count":24095785,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go-grpc","golang","grpc","protobuf","rpc","starter-kit","tls"],"created_at":"2025-07-28T08:49:44.396Z","updated_at":"2025-07-28T08:49:47.310Z","avatar_url":"https://github.com/muthu-kumar-u.png","language":"Go","readme":"# Go gPRC Starter\n\n\u003e A fully-featured, production-ready gRPC boilerplate in Go — complete with JWT authentication, TLS, validation, error handling, Envoy REST gateway, and more.\n\n---\n\n## Description\n\nThis repository demonstrates a **production-grade gRPC service** built in Go, showcasing best practices in secure communication, modular code structure, and robust error handling. It includes tools and configurations for real-world deployment, local development, and REST-to-gRPC bridging via Envoy.\n\nWhether you're starting a new microservice or modernizing an existing monolith, this boilerplate is a clean foundation for scalable, performant, and secure Go-based services.\n\n---\n\n## Features\n\n### Authentication\n\n- JWT-based auth using `RS256` with PEM key pair (`private.pem` / `public.pem`)\n- Tokens include standard and custom claims (`sub`, `iat`, `role`, etc.)\n- Server-side verification via `UnaryServerInterceptor`\n\n### Metadata Handling\n\n- Sends and parses custom metadata headers (e.g. Authorization token)\n- Uses `context.Context` with outgoing/incoming metadata\n\n### Custom Error Handling\n\n- Structured error response using custom `Error` protobuf\n- Wrapped with `google.golang.org/grpc/status` and `codes`\n- Uniform client-side error decoding with details\n\n### Field Validation\n\n- Custom validation logic in handler layer\n- Example: Rejects empty names with gRPC errors\n\n### TLS / SSL (Secure Transport)\n\n- Self-signed certs (`cert.pem`, `key.pem`) for local testing\n- Supports replacement with production-grade certs without code change\n- gRPC client configured with `credentials.NewClientTLSFromFile`\n\n### REST API via Envoy Proxy\n\n- REST-to-gRPC translation using Envoy\n- Accepts standard HTTP/JSON requests and forwards to gRPC backend\n- No BSR (Buf Schema Registry) required\n\n### Context \u0026 Deadlines\n\n- All client-server requests use `context.Context`\n- Deadline propagation supported with timeouts\n\n### Interceptors\n\n- Unary interceptors for:\n  - Logging\n  - Authentication\n  - Error translation\n\n### Shared Protobuf Definitions\n\n- Shared `proto/` folder between client and server\n- Uses `buf` for linting, breaking checks, and codegen\n\n### Build Tooling\n\n- `Makefile` includes:\n  - `make proto`: Compile all protos\n  - `make run-server`: Start the gRPC server\n  - `make run-client`: Run the test client\n\n### Client Example\n\n- Client includes:\n  - Auth token generation via `jwt-go`\n  - TLS transport\n  - Metadata headers\n  - Calls for `Create`, `Read`, `Write`, and `Delete`\n\n### Configuration\n\n- Centralized configuration via `config.yml`\n- Share JWT keys, TLS cert paths, and server address between components\n\n---\n\n## Quickstart\n\n### Prerequisites\n\n- Go ≥ 1.23\n- `buf` (https://buf.build/)\n- `make`\n- `docker` (for Envoy REST proxy)\n\n### 1. Generate Protobufs\n\n```bash\nmake proto\n```\n\n### 2. Run Server\n\n```bash\nmake run-server\n```\n\n### 3. Run Client\n\n```bash\nmake run-client\n```\n\n### 4. REST Testing via Envoy\n\n**This project includes a Docker-based Envoy proxy to bridge HTTP/JSON REST requests to your gRPC backend**\n\nSteps to Run Envoy:\n\n- Make sure the gRPC server is running on port 50051.\n- Build the Envoy Docker image from the provided Dockerfile:\n\n```bash\ndocker build -t go-grpc-envoy -f envoy/Dockerfile .\n```\n\n- Run the container:\n\n```bash\ndocker run --rm -p 8080:8080 --network host go-grpc-envoy\n```\n\n\u003e - **--network host** allows Envoy to communicate with the gRPC server on **localhost:50051**\n\u003e - If you're on macOS or Windows, replace **--network host** with appropriate Docker networking, or use **host.docker.internal** in the envoy.yaml.\n\n- Test using curl:\n\n```bash\ncurl -X POST http://localhost:8080/v1/users \\\n  -H \"Authorization: Bearer \u003cyour_jwt\u003e\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"test\", \"email\": \"test@test.com\", \"number\": \"1234567890\"}'\n```\n\n## TLS/SSL Notes\n\n| Environment | Setup                                                      |\n| ----------- | ---------------------------------------------------------- |\n| Local Dev   | Uses self-signed `cert.pem` and `key.pem`                  |\n| Production  | Replace certs in `certs/` folder, no code changes required |\n| Client      | Uses server’s `cert.pem` as CA cert                        |\n\n## JWT Auth Notes\n\n| File          | Purpose                   |\n| ------------- | ------------------------- |\n| `private.pem` | Signing key (client)      |\n| `public.pem`  | Verification key (server) |\n\n- Tokens issued by client via RSA\n- Claims are validated server-side via custom interceptor\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuthu-kumar-u%2Fgo-grpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmuthu-kumar-u%2Fgo-grpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuthu-kumar-u%2Fgo-grpc/lists"}