{"id":16345288,"url":"https://github.com/mirkolenz/grpc-proxy","last_synced_at":"2025-10-26T01:31:33.392Z","repository":{"id":174300154,"uuid":"652034911","full_name":"mirkolenz/grpc-proxy","owner":"mirkolenz","description":"Proxy server built on envoy providing a REST gateway and the ability to translate gRPC-Web and/or Connect requests requests into regular gRPC requests.","archived":false,"fork":false,"pushed_at":"2025-02-05T20:35:30.000Z","size":200,"stargazers_count":9,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-06T04:30:02.513Z","etag":null,"topics":["api","envoy","grpc","http","protobuf","proxy"],"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/mirkolenz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2023-06-10T21:57:13.000Z","updated_at":"2025-02-05T20:35:33.000Z","dependencies_parsed_at":"2023-10-25T08:58:33.077Z","dependency_job_id":"0c165185-3c05-4474-aa18-4d6d75859e22","html_url":"https://github.com/mirkolenz/grpc-proxy","commit_stats":{"total_commits":226,"total_committers":7,"mean_commits":"32.285714285714285","dds":0.5442477876106195,"last_synced_commit":"afcfe55dfa64164d3eef1eb7652624b8446d0965"},"previous_names":["mirkolenz/grpc-proxy"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mirkolenz%2Fgrpc-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mirkolenz%2Fgrpc-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mirkolenz%2Fgrpc-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mirkolenz%2Fgrpc-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mirkolenz","download_url":"https://codeload.github.com/mirkolenz/grpc-proxy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238241409,"owners_count":19439767,"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":["api","envoy","grpc","http","protobuf","proxy"],"created_at":"2024-10-11T00:30:38.955Z","updated_at":"2025-10-26T01:31:33.380Z","avatar_url":"https://github.com/mirkolenz.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gRPC Proxy for REST, gRPC-Web, and Connect\n\nProxy server built on [envoy](https://github.com/envoyproxy/envoy) providing a REST gateway and the ability to translate [gRPC-Web](https://github.com/grpc/grpc-web) and/or [Connect](https://connect.build) requests requests into regular [gRPC](https://github.com/grpc/grpc) requests.\nThe Go binaries are available via GitHub Releases and we also provide a Docker image and a Nix package.\n\n## Using the Full Distribution (with Envoy)\n\nFor most users, we recommend using our full distribution, which includes envoy.\n\n### Docker (recommended)\n\n```shell\ndocker run --rm -it -p 50052:50052 ghcr.io/mirkolenz/grpc-proxy:latest --proxy-port 50052 --backend-port 50051\n```\n\n### Nix (Linux only)\n\n```shell\nnix run github:mirkolenz/grpc-proxy#full -- --proxy-port 50052 --backend-port 50051\n```\n\n## Using the Binaries (without Envoy)\n\nFor this type of installation, we assume that you have envoy installed on your system.\nPlease refer to the [official documentation](https://www.envoyproxy.io/docs/envoy/latest/start/install) for instructions on how to install envoy.\nIf the envoy binary is not available in your `$PATH`, you can provide the path to the binary via the `--envoy` parameter.\n\n### Go\n\nFirst, install the binary:\n\n```shell\ngo install github.com/mirkolenz/grpc-proxy@latest\n```\n\nThen, run the proxy as follows:\n\n```shell\ngrpc-proxy --envoy /usr/bin/envoy --proxy-port 50052 --backend-port 50051\n```\n\n### Binary Downloads\n\nGo to the [latest GitHub Release](https://github.com/mirkolenz/grpc-proxy/releases/latest) and download the binary for your platform for the list of assets.\nThen, run the proxy as follows:\n\n```shell\n./grpc-proxy --envoy /usr/bin/envoy --proxy-port 50052 --backend-port 50051\n```\n\n### Nix (Linux and macOS)\n\n```shell\nnix run github:mirkolenz/grpc-proxy -- --proxy-port 50052 --backend-port 50051\n```\n\n## Special Considerations for the REST Gateway\n\nThe gRPC-Web and Connect translation works without any additional configuration.\nThe REST gateway requires the protobuf descriptor set as well as an explicit list of services to be exposed.\n\nIf you are already using [buf](https://buf.build), make sure to add `buf.build/googleapis/googleapis` to your `deps`.\nThen, you can generate the descriptor set as follows:\n\n```shell\nbuf build -o descriptor.binpb\n```\n\nWhen using plain `protoc`, please refer to the [official documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_json_transcoder_filter).\nBear in mind that in case of using Docker, you need to mount the descriptor set into the container (e.g., `-v $(pwd)/descriptor.binpb:/descriptor.binpb`).\nAfterwards, run the proxy as follows:\n\n```shell\ngrpc-proxy --proxy-port 50052 --backend-port 50051 --rest-proto-descriptor \"./descriptor.binpb\" --rest-services \"package1.ServiceA,package2.ServiceB\"\n```\n\n## Options and Help\n\n\u003c!-- echo -e \"\\n```txt\\n$(COLUMNS=80 go run . --help)\\n```\" \u003e\u003e README.md --\u003e\n\n```txt\nUsage: grpc-proxy --backend-port=BACKEND-PORT,... --proxy-port=INT [flags]\n\nFlags:\n  -h, --help                      Show context-sensitive help.\n      --version                   Print version information.\n      --access-log=/dev/stdout    Access log files.\n      --envoy=\"envoy\"             Path to the envoy executable. If set to an\n                                  empty string, the config will only be printed.\n\nBackend Options\n  --backend-host=\"127.0.0.1\"    Host address of the backend.\n  --backend-port=BACKEND-PORT,...\n                                Port of the backend. Multiple can be provided to\n                                enable load balancing via round robin.\n  --backend-timeout=120         Timeout in seconds for requests sent to the\n                                backend.\n\nProxy Options\n  --proxy-host=\"127.0.0.1\"    Host address of the envoy proxy.\n  --proxy-port=INT            Port of the envoy proxy.\n\nAdmin Options\n  --admin-host=\"127.0.0.1\"    Host address of the admin interface.\n  --admin-port=INT            Port of the admin interface.\n\nCluster Options\n  --cluster-dns-lookup-family=\"V4_PREFERRED\"\n      The DNS IP address resolution policy.\n  --cluster-load-balance-policy=\"ROUND_ROBIN\"\n      The load balancer type to use when picking a host in the cluster.\n  --cluster-discovery-type=\"STRICT_DNS\"\n      The service discovery type to use for resolving the cluster.\n  --cluster-connect-timeout=0.25\n      The timeout in seconds for new network connections to hosts in the\n      cluster.\n  --cluster-max-concurrent-streams=100\n      Maximum concurrent streams allowed for peer on one HTTP/2 connection.\n\nREST Gateway Options\n  --rest-proto-descriptor=STRING\n                                  Supplies the filename of the proto descriptor\n                                  set for the gRPC services.\n  --rest-proto-descriptor-bin=STRING\n                                  Supplies the binary content of the proto\n                                  descriptor set for the gRPC services.\n  --rest-services=REST-SERVICES,...\n                                  A list of strings that supplies the\n                                  fully qualified service names (i.e.\n                                  “package_name.service_name”) that the\n                                  transcoder will translate. If the service\n                                  name doesn't exist in proto_descriptor, Envoy\n                                  will fail at startup. The proto_descriptor may\n                                  contain more services than the service names\n                                  specified here, but they won’t be translated.\n                                  By default, the filter will pass through\n                                  requests that do not map to any specified\n                                  services. If the list of services is empty,\n                                  filter is considered disabled. However,\n                                  this behavior changes if reject_unknown_method\n                                  is enabled.\n  --[no-]rest-auto-mapping        Whether to route methods without the\n                                  google.api.http option.\n  --rest-convert-grpc-status      Whether to convert gRPC status headers to\n                                  JSON. When trailer indicates a gRPC error and\n                                  there was no HTTP body, take google.rpc.Status\n                                  from the grpc-status-details-bin header\n                                  and use it as JSON body. If there was no\n                                  such header, make google.rpc.Status out of\n                                  the grpc-status and grpc-message headers.\n                                  The error details types must be present in the\n                                  proto_descriptor.\n  --rest-url-unescape-spec=\"ALL_CHARACTERS_EXCEPT_RESERVED\"\n                                  URL unescaping policy. This spec is only\n                                  applied when extracting variable with multiple\n                                  segments in the URL path. For example,\n                                  in case of /foo/{x=*}/bar/{y=prefix/*}/{z=**}\n                                  x variable is single segment and y and\n                                  z are multiple segments. For a path with\n                                  /foo/first/bar/prefix/second/third/fourth,\n                                  x=first, y=prefix/second, z=third/fourth.\n                                  If this setting is not specified, the value\n                                  defaults to ALL_CHARACTERS_EXCEPT_RESERVED.\n  --rest-query-param-unescape-plus\n                                  If true, unescape + to space when extracting\n                                  variables in query parameters. This is to\n                                  support HTML 2.0\n  --rest-match-unregistered-custom-verb\n                                  If true, try to match the custom verb even\n                                  if it is unregistered. By default, only match\n                                  when it is registered. According to the http\n                                  template syntax, the custom verb is “:”\n                                  LITERAL at the end of http template.\n  --rest-case-insensitive-enum-parsin\n                                  Proto enum values are supposed to be in upper\n                                  cases when used in JSON. Set this to true if\n                                  your JSON request uses non uppercase enum\n                                  values.\n  --rest-max-request-body-size=10000000\n                                  The maximum size of a request body to be\n                                  transcoded, in bytes. A body exceeding this\n                                  size will provoke a HTTP 413 Request Entity\n                                  Too Large response. Large values may cause\n                                  envoy to use a lot of memory if there are many\n                                  concurrent requests.\n  --rest-max-response-body-size=10000000\n                                  The maximum size of a response body to be\n                                  transcoded, in bytes. A body exceeding this\n                                  size will provoke a HTTP 500 Internal Server\n                                  Error response. Large values may cause envoy\n                                  to use a lot of memory if there are many\n                                  concurrent requests.\n  --rest-ignore-unknown-query-parameters\n                                  Whether to ignore query parameters that cannot\n                                  be mapped to a corresponding protobuf field.\n                                  Use this if you cannot control the query\n                                  parameters and do not know them beforehand.\n                                  Otherwise use ignored_query_parameters.\n                                  Defaults to false.\n  --rest-ignored-query-parameters=REST-IGNORED-QUERY-PARAMETERS,...\n                                  A list of query parameters to be ignored\n                                  for transcoding method mapping. By default,\n                                  the transcoder filter will not transcode a\n                                  request if there are any unknown/invalid query\n                                  parameters.\n  --[no-]rest-add-whitespace      Whether to add spaces, line breaks and\n                                  indentation to make the JSON output easy to\n                                  read. Defaults to true.\n  --rest-always-print-primitive-fields\n                                  Whether to always print primitive fields. By\n                                  default primitive fields with default values\n                                  will be omitted in JSON output. For example,\n                                  an int32 field set to 0 will be omitted.\n                                  Setting this flag to true will override the\n                                  default behavior and print primitive fields\n                                  regardless of their values. Defaults to false.\n  --rest-always-print-enums-as-ints\n                                  Whether to always print enums as ints.\n                                  By default they are rendered as strings.\n                                  Defaults to false.\n  --rest-preserve-proto-field-names\n                                  Whether to preserve proto field names.\n                                  By default protobuf will generate JSON field\n                                  names using the json_name option, or lower\n                                  camel case, in that order. Setting this flag\n                                  will preserve the original field names.\n                                  Defaults to false.\n  --rest-stream-newline-delimited\n                                  If true, return all streams as\n                                  newline-delimited JSON messages instead of as\n                                  a comma-separated array.\n  --rest-reject-unknown-method    By default, a request that cannot be mapped to\n                                  any specified gRPC services will pass-through\n                                  this filter. When set to true, the request\n                                  will be rejected with a HTTP 404 Not Found.\n  --rest-reject-unknown-query-parameters\n                                  By default, a request with query parameters\n                                  that cannot be mapped to the gRPC request\n                                  message will pass-through this filter.\n                                  When set to true, the request will be rejected\n                                  with a HTTP 400 Bad Request.\n  --rest-reject-binding-body-field-collisions\n                                  If this field is set to true, the request will\n                                  be rejected if the binding value is different\n                                  from the body value.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmirkolenz%2Fgrpc-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmirkolenz%2Fgrpc-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmirkolenz%2Fgrpc-proxy/lists"}