{"id":16275254,"url":"https://github.com/ncrypthic/graphql-grpc-edge","last_synced_at":"2025-03-20T01:30:48.343Z","repository":{"id":44775527,"uuid":"226464636","full_name":"ncrypthic/graphql-grpc-edge","owner":"ncrypthic","description":"EXPERIMENTAL work to automatically generate graphql server as aggregate server to serve gRPC backed service","archived":false,"fork":false,"pushed_at":"2024-05-19T08:48:19.000Z","size":146,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-06-19T18:08:32.897Z","etag":null,"topics":["graphql","grpc","protoc-plugin"],"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/ncrypthic.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}},"created_at":"2019-12-07T06:09:28.000Z","updated_at":"2024-05-14T07:39:39.000Z","dependencies_parsed_at":"2022-08-21T04:40:51.684Z","dependency_job_id":null,"html_url":"https://github.com/ncrypthic/graphql-grpc-edge","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncrypthic%2Fgraphql-grpc-edge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncrypthic%2Fgraphql-grpc-edge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncrypthic%2Fgraphql-grpc-edge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ncrypthic%2Fgraphql-grpc-edge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ncrypthic","download_url":"https://codeload.github.com/ncrypthic/graphql-grpc-edge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219865974,"owners_count":16555917,"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":["graphql","grpc","protoc-plugin"],"created_at":"2024-10-10T18:32:38.186Z","updated_at":"2024-10-10T18:32:38.254Z","avatar_url":"https://github.com/ncrypthic.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# graphql-grpc-edge\n\nThis repo is an **EXPERIMENTAL** work to automatically generate graphql server\nas aggregate server to serve gRPC backed service.\n\n## Background\n\ngRPC and GraphQL are application level communication protocol designed to solve different set of problems. Both gRPC and GraphQL using different serialization and specification but shares same characteristics and functionalities as listed below.\n\nSame specification characteristics between protobuf to grphql schema:\n\n|  Protobuf   | GraphQL                                    |\n|-------------|--------------------------------------------|\n|  Package    | N/A                                        |\n|  Service    | N/A                                        |\n|  Import     | N/A                                        |\n|  Enum       | Enum                                       |\n|  Oneof      | Union                                      |\n|  Message    | Type                                       |\n|  Field      | Field                                      |\n|  RPC        | `Query` or `Mutation`                      |\n|  RPC Input  | `InputObject` with `option (graphql.type)` |\n|  RPC Output | `Object` with `option (graphql.type)`.     |\n\nSame primitive serialization data types:\n\n| Protobuf | GraphQL. |\n|----------|----------|\n| uint8    | Int      |\n| uint16   | Int      |\n| uint32   | Int      |\n| uint64   | Int      |\n| int8     | Int      |\n| int16    | Int      |\n| int32    | Int      |\n| int64    | Int      |\n| float32  | Float    |\n| float64  | Float    |\n| string   | String   |\n| bool     | Boolean  |\n\n## Goals\n\nCreate a tool to get the best of both worlds. gRPC is very helpful to develop backend service. With gRPC, API contracts can be described concisely and also code implementation can be autogenerated. Unfortunately, as of this repository is created, there is no easy way to use gRPC directly from web browsers for web application. On the otherhand, GraphQL is very popular on web frontend community thanks to its flexible query fields resulting in efficient network transfer size, and graph-like data representation very helpful for frontend engineer. One of the downsize of using GraphQL is there's no easy way to generate a GraphQL schema.\n\nIt is possible to create a GraphQL server and schema to be used by frontend engineer while communicating to backend services using gRPC to return the results. But to do this manually will be very tedious.\n\n## Design\n\n![Design diagram](docs/diagram.png)\n\n## Usage\n\n1. Install `protoc-gen-graphql` executable with `go get github.com/ncrypthic/graphql-grpc-edge/protoc-gen-graphql`.\n\n2. Import `graphql-grpc-edge/graphql/graphql.proto` protobuf file.\n\n3. Add `graphql.type` option to `service.rpc`(s) to generate graphql operation type (Query, Mutation) along with the operation name. For example:\n\n    ```proto\n    syntax=\"proto3\";\n\n    // ...\n    import \"graphql-grpc-edge/graphql/graphql.proto\";\n\n    // ...\n    service Example {\n        rpc GetSomething(GetSomethingRequest) returns(GetSomethingResponse) {\n            option (graphql.type) = {\n                // this will generate a graphql query named `getSomething` with `GetSomethingRequestInput` as its parameter\n                // and `GetSomethingResponse` object as its return type\n                query: \"getSomething\"\n            };\n        }\n\n        rpc MutateSomething(MutateSomethingRequest) returns(MutateSomethingResponse) {\n            option (graphql.type) = {\n                // this will generate a graphql mutation named `mutateSomething` with `MutateSomethingRequest` as its parameter\n                // and `MutateSomethingResponse` object as its return type\n                mutation: \"mutateSomething\"\n            };\n        }\n    }\n    ```\n\n5. Generate golang code using `protoc --graphql_out=:. file.proto`\n\n6. Register generated graphql types, queries and mutations. Using example generated code from proto definition above:\n\n    ```golang\n    import (\n        \"github.com/graphql-go/handler\"\n        edge \"github.com/ncrypthic/graphql-grpc-edge/graphql\"\n    )\n\n    // ...\n    // grpcClient: grpcClient to upstream gRPC server\n\n    somePackage.RegisterExampleServiceTypes()\n    somePackage.RegisterExampleServiceQueries(grpcClient)\n    somePackage.RegisterExampleServiceMutations(grpcClient)\n\n    gqlSchema := edge.GetSchema()\n    ```\n\n7. Serve the graphql schema\n\n    ```golang\n    import (\n        \"github.com/graphql-go/handler\"\n        edge \"github.com/ncrypthic/graphql-grpc-edge/graphql\"\n    )\n\n    // ...\n\n    somePackage.RegisterExampleServiceTypes()\n    somePackage.RegisterExampleServiceQueries(grpcClient)\n    somePackage.RegisterExampleServiceMutations(grpcClient)\n\n    gqlSchema := edge.GetSchema()\n    h := handler.New(\u0026handler.Config{\n        Schema:   schema,\n        Pretty:   true,\n        GraphiQL: true,\n    })\n\n    http.HandleFunc(\"/graphql\", func(w http.ResponseWriter, req *http.Request) {\n        // Optional: enable opentracing\n        span, ctx := opentracing.StartSpanFromContext(context.Background(), \"entrypoint\")\n        defer span.Finish()\n        // Handle graphql API\n        h.ContextHandler(ctx, w, req)\n    })\n    ```\n\n## More example\n\nSee [example](example)\n\n\n## License\n\nMIT License\n\nCopyright (c) 2019 Lim Afriyadi\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncrypthic%2Fgraphql-grpc-edge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fncrypthic%2Fgraphql-grpc-edge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fncrypthic%2Fgraphql-grpc-edge/lists"}