{"id":21064162,"url":"https://github.com/moveaxlab/go-grpc-server","last_synced_at":"2026-04-23T12:31:42.637Z","repository":{"id":224573345,"uuid":"759910920","full_name":"moveaxlab/go-grpc-server","owner":"moveaxlab","description":"Utilities to create gRPC servers in Go, including some interceptors.","archived":false,"fork":false,"pushed_at":"2024-03-01T09:01:18.000Z","size":38,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-01T09:16:28.763Z","etag":null,"topics":["go","grpc","protobuf","server"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moveaxlab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2024-02-19T15:15:01.000Z","updated_at":"2024-02-26T15:31:13.000Z","dependencies_parsed_at":"2024-02-26T17:55:44.679Z","dependency_job_id":"83e04384-59e2-4983-b093-0856922b96b8","html_url":"https://github.com/moveaxlab/go-grpc-server","commit_stats":null,"previous_names":["moveaxlab/go-grpc-server"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/moveaxlab/go-grpc-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moveaxlab%2Fgo-grpc-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moveaxlab%2Fgo-grpc-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moveaxlab%2Fgo-grpc-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moveaxlab%2Fgo-grpc-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moveaxlab","download_url":"https://codeload.github.com/moveaxlab/go-grpc-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moveaxlab%2Fgo-grpc-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32181365,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T11:42:27.955Z","status":"ssl_error","status_checked_at":"2026-04-23T11:42:18.877Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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","protobuf","server"],"created_at":"2024-11-19T17:48:31.346Z","updated_at":"2026-04-23T12:31:42.620Z","avatar_url":"https://github.com/moveaxlab.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go gRPC server utilities\n\nThis repo contains utilities to build gRPC server.\nThese include useful interceptors, health checks, metrics,\nand functions to start and stop the gRPC server.\n\n## Installation\n\n```bash\ngo get github.com/moveaxlab/go-grpc-server\n```\n\n## Create the server\n\nThis package provides utilities to create, start, and stop gRPC servers.\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"os/signal\"\n\t\"sync\"\n\t\"syscall\"\n\n\t\"github.com/moveaxlab/go-grpc-server\"\n)\n\nfunc main() {\n\tserver := grpc_server.NewGrpcServer(40051)\n\twg := \u0026sync.WaitGroup{}\n\tchannel := make(chan os.Signal, 1)\n\n\t// register your gRPC services\n\tvar myService mypackage.MyServiceServer\n\t// initialize the myService variable\n\tmypackage.RegisterMyServiceServer(server.GetServer(), myService)\n\n\t// start the server\n\tserver.Start()\n\n\t// stop the server gracefully\n\tsignal.Notify(channel, syscall.SIGINT)\n\tsignal.Notify(channel, syscall.SIGTERM)\n\n\twg.Add(1)\n\tgo func() {\n\t\tdefer wg.Done()\n\t\tselect {\n\t\tcase \u003c-channel:\n\t\t\terr := server.Stop()\n\t\t\tif err != nil {\n\t\t\t\tfmt.Printf(\"server stop returned an error: %v\", err)\n\t\t\t}\n\t\t}\n\n\t}()\n\twg.Wait()\n}\n```\n\nImplementing a new gRPC service requires the following steps:\n\n1. generate code from your proto files, using `protoc`, `protoc-gen-go`, and `protoc-gen-go-grpc`\n2. implement the service with a struct that embeds the `mypackage.MyServiceServer` interface\n3. register it before the gRPC server start with `mypackage.RegisterMyServiceServer`,\n   passing it the result of `server.GetServer()` as first argument\n\nThe server registers automatically the [standard health service](https://grpc.io/docs/guides/health-checking/),\nand sets its status to running as soon as the gRPC server is started.\n\n### Metrics\n\nThe gRPC server provides metrics with the `GetMetrics()` method,\nwhich returns a list of `github.com/prometheus/client_golang/prometheus.Collector`.\n\nUsing interceptors will enable different metrics.\n\n## Interceptors\n\nThe gRPC server constructor function accepts a list of `google.golang.org/grpc.UnaryServerInterceptor`\nthat will be registered in the order they are passed.\n\nWe provide a few useful interceptors.\nThe suggested order of registration is the following:\n\n- `StatusInterceptor` handles non-application errors\n- `NewMetricsInterceptor()` tracks prometheus metrics for your application\n- `ValidationInterceptor` validates requests using `protoc-gen-validate`\n- `NewErrorInterceptor()` handles application errors\n- `RecoverInterceptor` recovers from panics occurring in the application\n\n### Recovering from panics\n\nThe `grpc_server.RecoverInterceptor` recovers from panics downstream in your application.\nAdd it at the end of your interceptor list, and you can `panic` as much as you want\ninside your application code.\n\nThe recovered errors will be returned as the second result from the `handler` function\nin upstream interceptors.\n\n### Handling application errors\n\nThis package provides the `grpc_server.ApplicationError` interface that can be implemented\nby your application errors. This interface requires you to implement the `GRPCStatus()`\nmethod, that converts the error to a `google.golang.org/grpc/status.Status` object,\nand the `Trailer()` method that returns the trailing metadata that must be returned to the caller.\n\nOnce you have defined your application errors, call the `grpc_server.NewErrorInterceptor()`\nto initialize the interceptor, and add it to your gRPC server.\n\nInitializing this interceptor adds the `grpc_request_application_error_count_total` prometheus metric\nto the gRPC server, which counts application errors.\n\n### Validating requests\n\nIf you are using [`protoc-gen-validate`](https://github.com/bufbuild/protoc-gen-validate)\non incoming requests, you can add the `grpc_server.ValidationInterceptor` to your gRPC server.\nThis interceptor will validate incoming requests, and return an error if validation does not pass.\n\n### Collecting metrics\n\nYou can use the `grpc_server.NewMetricsInterceptor` function to create an interceptor\nthat collects metrics on requests you received using prometheus.\nInitializing this interceptor will register the following metrics:\n\n- `grpc_request_time_ms` tracks time taken by all requests\n- `grpc_request_count_total` tracks the number of requests received\n- `grpc_request_error_count_total` tracks the number of requests that failed for any reason\n\nThe function that creates the interceptor takes in input\na list of endpoints that will be ignored.\nThis can be used if you don't want to track metrics on certain endpoints,\ne.g. for the health check endpoint.\n\n### Unhandled errors\n\nThe `grpc_server.StatusInterceptor` adds the internal status code to responses\nif the service returned an error and it was not handled by other interceptors.\n\nThis should be your first interceptor.\n\n## Custom interceptors\n\nYou can implement custom interceptors that use your custom application logic.\n\nThis interceptor extracts user info from the request metadata,\nand stores them in the request context:\n\n```go\nimport (\n\t\"context\"\n\n\t\"google.golang.org/grpc\"\n\t\"google.golang.org/grpc/metadata\"\n)\n\nfunc SecurityInterceptor(\n\tctx context.Context,\n\treq interface{},\n\tinfo *grpc.UnaryServerInfo,\n\thandler grpc.UnaryHandler,\n) (resp interface{}, err error) {\n\tmd, hasMetadata := metadata.FromIncomingContext(ctx)\n\n\tif hasMetadata {\n\t\tctx = AddUserToContext(ctx, md)\n\t}\n\n\treturn handler(ctx, req)\n}\n```\n\nThis is what a Sentry interceptor would look like,\nthat sends non-application errors to Sentry and tracks user info:\n\n```go\nimport (\n\t\"context\"\n\n\t\"github.com/moveaxlab/go-grpc-server\"\n\t\"github.com/getsentry/sentry-go\"\n\t\"google.golang.org/grpc\"\n)\n\nfunc SentryInterceptor(\n\tctx context.Context,\n\treq interface{},\n\tinfo *grpc.UnaryServerInfo,\n\thandler grpc.UnaryHandler,\n) (resp interface{}, err error) {\n\tresp, err = handler(ctx, req)\n\n\t// skip reporting application errors to sentry\n\tif err == nil || grpc_server.IsApplicationError(err) {\n\t\treturn resp, nil\n\t}\n\n\tsentry.WithScope(func(scope *sentry.Scope) {\n\t\t// your custom logic to retrieve the user from the context\n\t\tif user, hasUser := GetUser(ctx); hasUser {\n\t\t\tscope.SetUser(sentry.User{\n\t\t\t\tID: user.Id(),\n\t\t\t})\n\t\t}\n\n\t\tscope.SetExtras(map[string]interface{}{\n\t\t\t\"endpoint\": info.FullMethod,\n\t\t\t\"request\":  req,\n\t\t})\n\n\t\tsentry.CaptureException(err)\n\t})\n\n\treturn nil, err\n}\n```\n\nThis interceptor should be registered after the `SecurityInterceptor` example given above.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoveaxlab%2Fgo-grpc-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoveaxlab%2Fgo-grpc-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoveaxlab%2Fgo-grpc-server/lists"}