{"id":13740411,"url":"https://github.com/gdong42/grpc-mate","last_synced_at":"2025-05-08T20:31:20.627Z","repository":{"id":84781942,"uuid":"188578324","full_name":"gdong42/grpc-mate","owner":"gdong42","description":"A dynamic proxy server that translates JSON HTTP requests into gRPC calls.","archived":false,"fork":false,"pushed_at":"2019-07-05T00:28:45.000Z","size":3634,"stargazers_count":74,"open_issues_count":9,"forks_count":9,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-08-04T04:06:34.044Z","etag":null,"topics":["grpc","grpc-gateway","grpc-mate","grpc-proxy","rest-api"],"latest_commit_sha":null,"homepage":"https://grpcmate.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gdong42.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}},"created_at":"2019-05-25T14:49:26.000Z","updated_at":"2024-07-22T14:43:25.000Z","dependencies_parsed_at":"2023-03-13T02:29:41.932Z","dependency_job_id":null,"html_url":"https://github.com/gdong42/grpc-mate","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gdong42%2Fgrpc-mate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gdong42%2Fgrpc-mate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gdong42%2Fgrpc-mate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gdong42%2Fgrpc-mate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gdong42","download_url":"https://codeload.github.com/gdong42/grpc-mate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224765461,"owners_count":17366123,"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","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":["grpc","grpc-gateway","grpc-mate","grpc-proxy","rest-api"],"created_at":"2024-08-03T04:00:47.490Z","updated_at":"2024-11-15T10:30:39.501Z","avatar_url":"https://github.com/gdong42.png","language":"Go","funding_links":[],"categories":["Tools"],"sub_categories":["Other"],"readme":"# gRPC Mate\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/gdong42/grpc-mate)](https://goreportcard.com/report/github.com/gdong42/grpc-mate)\n[![Build Status](https://travis-ci.com/gdong42/grpc-mate.svg?branch=master)](https://travis-ci.com/gdong42/grpc-mate)\n[![Docker Pulls](https://img.shields.io/docker/pulls/gdong/grpc-mate.svg)](https://hub.docker.com/r/gdong/grpc-mate)\n[![MicroBadger Size (tag)](https://img.shields.io/microbadger/image-size/gdong/grpc-mate/latest.svg)](https://hub.docker.com/r/gdong/grpc-mate)\n[![Docker Image](https://images.microbadger.com/badges/version/gdong/grpc-mate.svg)](https://hub.docker.com/r/gdong/grpc-mate)\n\ngRPC Mate is a light weight reverse proxy server that translates JSON HTTP requests into gRPC calls without the need of \ncode generation. It reads protobuf service definitions through accessing reflection API exposed by the gRPC service, \nand converts HTTP and JSON requests to gRPC invocations dynamically.\n\nThe purpose that gRPC Mate is created is to provide a way to serve HTTP and JSON from a gRPC server very easily, without \nprotobuf definition files sharing, without protobuf directives, and without any Service Discovery system integration. \n\nAs its name *gRPC Mate* suggestes, the reverse proxy server is designed to be a sidecar, and is expected to run beside \nthe proxied gRPC server. In a development or testing scenario, it can be dropped with mere configuration in front of the\ntarget gRPC service. In a production environment, instead of running a single gRPC Mate server in front all gRPC services,\nit is better to be deployed alongside each gRPC server instances, for example, as another container in the same pod if \nrunning within Kubernetes cluster.\n\n## Features\n\n* **HTTP to gRPC Translation** - Translates gRPC services into HTTP JSON endpoints.\n* **Independent Reverse Proxy** - Runs as an independent proxy server against upstream gRPC service, and evolving of the underlying gRPC service does not require an upgrade or rebuild\nof gRPC Mate server.\n* **Easy to Setup** - Requires only 1) the upstream gRPC server enabling gRPC reflection service, and 2) the gRPC listening address and port passing to gRPC Mate.\n* **Management Endpoints** - Provides basic management endpoints, such as `/actuator/health` \ntelling if the service is healthy, and `/actuator/services` introspecting all services, methods, their HTTP route mappings and request/response schema example.\n\n## Installation\n\nIt's recommended to use pre-built docker image `gdong/grpc-mate` directly. You can also choose to build from source.\n\n### Build from source\n\n1. Clone this repo\n    ```\n    git clone git@github.com:gdong42/grpc-mate.git\n    ```\n2. Install Go SDK if it's not installed yet, e.g.\n   ```\n   brew install go\n   brew install dep\n   ```\n3. Setup `GOPATH` if not yet, go to grpc-mate dir, install dependencies and build binary\n    ```\n    dep ensure\n    go build -o grpc-mate\n    ```\nNow grpc-mate command is built, following sections show how you configure and run it.\n\n## Quick Start\n\n### Prerequisites\n\nMake sure [Server Reflection](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md) is enabled on gRPC target server side.\n* For server written in Java, refer to [this guide](https://github.com/grpc/grpc-java/blob/master/documentation/server-reflection-tutorial.md)\n    ```diff\n    --- a/examples/build.gradle\n    +++ b/examples/build.gradle\n    @@ -27,6 +27,7 @@\n    dependencies {\n    compile \"io.grpc:grpc-netty-shaded:${grpcVersion}\"\n    compile \"io.grpc:grpc-protobuf:${grpcVersion}\"\n    +  compile \"io.grpc:grpc-services:${grpcVersion}\"\n    compile \"io.grpc:grpc-stub:${grpcVersion}\"\n    \n    testCompile \"junit:junit:4.12\"\n    --- a/examples/src/main/java/io/grpc/examples/helloworld/HelloWorldServer.java\n    +++ b/examples/src/main/java/io/grpc/examples/helloworld/HelloWorldServer.java\n    @@ -33,6 +33,7 @@ package io.grpc.examples.helloworld;\n    \n    import io.grpc.Server;\n    import io.grpc.ServerBuilder;\n    +import io.grpc.protobuf.services.ProtoReflectionService;\n    import io.grpc.stub.StreamObserver;\n    import java.io.IOException;\n    import java.util.logging.Logger;\n    @@ -50,6 +51,7 @@ public class HelloWorldServer {\n        int port = 50051;\n        server = ServerBuilder.forPort(port)\n            .addService(new GreeterImpl())\n    +        .addService(ProtoReflectionService.newInstance())\n            .build()\n            .start();\n        logger.info(\"Server started, listening on \" + port);\n    ```\n* For server written in Go, refer to [this guide](https://github.com/grpc/grpc-go/blob/master/Documentation/server-reflection-tutorial.md)\n    ```diff\n    --- a/examples/helloworld/greeter_server/main.go\n    +++ b/examples/helloworld/greeter_server/main.go\n    @@ -40,6 +40,7 @@ import (\n            \"google.golang.org/grpc\"\n            pb \"google.golang.org/grpc/examples/helloworld/helloworld\"\n    +       \"google.golang.org/grpc/reflection\"\n    )\n\n    const (\n    @@ -61,6 +62,8 @@ func main() {\n            }\n            s := grpc.NewServer()\n            pb.RegisterGreeterServer(s, \u0026server{})\n    +       // Register reflection service on gRPC server.\n    +       reflection.Register(s)\n            if err := s.Serve(lis); err != nil {\n                    log.Fatalf(\"failed to serve: %v\", err)\n            }\n    ```\n\nFor demonstration, we start the gRPC example server with reflection enabled provided at https://github.com/grpc/grpc-go/tree/master/examples/features/reflection\n\n```\n$ go run server/main.go\nserver listening at [::]:50051\n```\n\n### Run gRPC Mate\n\nIt's really simple to run. Let's connect to the gRPC server started above as an example, using docker or command built from source.\n\n#### Run gRPC Mate via Docker\n\n```\n$ docker run --name grpc-mate -e GRPC_MATE_PROXIED_HOST=\u003cyour grpc server local IP\u003e -e GRPC_MATE_PROXIED_PORT=50051 -dp 6600:6600 gdong/grpc-mate\n```\n\nNote above `GRPC_MATE_PROXIED_HOST` has to be set to your IP address other than localhost, so that grpc-mate running inside docker can access it.\n\n#### Run gRPC Mate directly\n```\n$ GRPC_MATE_PROXIED_PORT=50051 ./grpc-mate\n```\nThis by default listens on 6600 as HTTP port, and connects to a local gRPC server running at `localhost:50051`\n\nTo connect to other gRPC server host and port, refer to the configuration section.\n\n### Introspecting Services\n\nNow try get `http://localhost:6600/actuator/services`, you will see all services the server exposes, as well as their enclosing methods, input and output types, e.g. one element of `services`:\n```\n      {  \n         \"name\":\"helloworld.Greeter\",\n         \"methods\":[  \n            {  \n               \"name\":\"SayHello\",\n               \"input\":\"helloworld.HelloRequest\",\n               \"output\":\"helloworld.HelloReply\",\n               \"route\":\"/helloworld.Greeter/SayHello\"\n            }\n         ]\n      }\n```\n It also has request/response JSON templates, convenient for construcing HTTP and JSON requests, e.g. one element of `types`:\n\n```\n      {  \n         \"name\":\"helloworld.HelloRequest\",\n         \"template\":{  \n            \"name\":\"\"\n         }\n      }\n\n```\n\n### Making Requests\n\nNow let's try making gRPC requests using above inspected information\n\n```\n$ curl -X POST -d '{\"name\":\"gdong42\"}' \"http://localhost:6600/v1/helloworld.Greeter/SayHello\" \n{\"message\":\"Hello gdong42\"}\n```\nAbove we invoked `SayHello` method of `helloworld.Greeter` service, with JSON message of `helloworld.HelloRequest` type, and got a JSON message of `helloworld.HelloReply` type.\n\nNote the HTTP method is POST, the body is a JSON string, and the request path is of pattern `/v1/{serviceName}/{methodName}`.\n\n## Configuration\n\ngRPC Mate is configured via a group of `GRPC_MATE_` prefixed Environment variables. They are\n\n* `GRPC_MATE_PORT`: the HTTP Port grpc-mate listens on, defaults to 6600\n* `GRPC_MATE_PROXIED_HOST`: the backend gRPC Host grpc-mate connects to, defaults to 127.0.0.1\n* `GRPC_MATE_PROXIED_PORT`: the backend gRPC Port grpc-mate connects to, defaults to 9090\n* `GRPC_MATE_LOG_LEVEL`: the log level, must be INFO, DEBUG, or ERROR, defaults to INFO\n\n## Limitation\n\nCurrently, gRPC Mate works with Unary calls only. We are working on support Streaming as well.\n\n## Contributing\n\nAll kinds of contribution are welcome!\n\n## Credits\n* [mercari/grpc-http-proxy](https://github.com/mercari/grpc-http-proxy) - gRPC Mate project is originally forked from this project. Although going towards different directions in [design decisions](https://github.com/gdong42/grpc-mate/blob/master/DESIGN.md), many coding implementations are borrowed from it.\n* [jhump/protoreflect](https://github.com/jhump/protoreflect) - The main lowlevel building block, which does the heavy lifting.\n* [fullstorydev/grpcurl](https://github.com/fullstorydev/grpcurl) - A useful command line tool to interact with gRPC service, gRPC Mate is also like the HTTP interface of this cli tool. A good example of protoreflect usage mentioned above.\n\n## License\n\nApache License 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgdong42%2Fgrpc-mate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgdong42%2Fgrpc-mate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgdong42%2Fgrpc-mate/lists"}