johanbrandhorst / grpc-gateway-boilerplate Goto Github PK

View Code? Open in Web Editor NEW

469.0 9.0 81.0 29.49 MB

All the boilerplate you need to get started with writing grpc-gateway powered REST services in Go

License: MIT License

Makefile 4.46% Go 81.14% Dockerfile 2.12% Shell 12.27%

grpc-gateway-boilerplate's Introduction

grpc-gateway-boilerplate

All the boilerplate you need to get started with writing grpc-gateway powered REST services in Go.

Requirements

Go 1.17+

Running

Running main.go starts a web server on https://0.0.0.0:11000/. You can configure the port used with the $PORT environment variable, and to serve on HTTP set $SERVE_HTTP=true.

$ go run main.go

An OpenAPI UI is served on https://0.0.0.0:11000/.

Running the standalone server

If you want to use a separate gRPC server, for example one written in Java or C++, you can run the standalone web server instead:

$ go run ./cmd/standalone/ --server-address dns:///0.0.0.0:10000

Getting started

After cloning the repo, there are a couple of initial steps;

If you forked this repo, or cloned it into a different directory from the github structure, you will need to correct the import paths. Here's a nice find one-liner for accomplishing this (replace yourscmprovider.com/youruser/yourrepo with your cloned repo path):
```
$ find . -path ./vendor -prune -o -type f $ -name '*.go' -o -name '*.proto' -o -name '*.yaml' $ -exec sed -i -e "s;github.com/johanbrandhorst/grpc-gateway-boilerplate;yourscmprovider.com/youruser/yourrepo;g" {} +
```
Finally, generate the files with make generate.

Now you can run the web server with go run main.go.

Making it your own

The next step is to define the interface you want to expose in proto/users/v1/user.proto. See https://developers.google.com/protocol-buffers/ tutorials and guides on writing Protobuf files. See the Buf style guide for tips on how to structure your packages.

Once that is done, regenerate the files using make generate. This will mean you'll need to implement any functions in server/server.go, or else the build will fail since your struct won't be implementing the interface defined by the generated files anymore.

This should hopefully be all you need to get started playing around with the gRPC-Gateway!

grpc-gateway-boilerplate's People

Contributors

Stargazers

Watchers

Forkers

randydom alan-ma-umg watano mmanjoura micro-community enerj lampnick erikperttu thomasvnn wfxr mtyrrell scfobao xydinesh claudiocleberson urunimi treble37 jns4u dmitris akaamo mghaderyan meysamghaderyan-vungle kushsharma abhishekvrshny xirdigh gitjaesik gustavilo cxsu merefield isgasho ivan-valkov obrientimothya hrabalvojta vicnoah kennychenfight ddavtian sam-ogden1 colbysadams binaryphile xkits cao7113 phamkhoa96 vasanthkumar97 toannhu96 pankaj4mhp smaruf ratakefumi jianxx zm-labo backmarket-oss brady1408 xushaoxiao sausax ajishcherian1982 linhbkhn95 dfang tonyxu1 tantona kasunjkd ram-cse luisespinal vominhtrius hieunmg clavinjune supermajestcd vdksystem zhb127 eyalkeren1 pushpakmittal chungpv elx123 greydoubt sam80719 zilonglym insanitywholesale anhnmt widerschein jagrutiti randy-rieger doraa7 prateek-forks ujangpudin04

grpc-gateway-boilerplate's Issues

Cannot find module for path embed

Hi there, thanks for providing this boilerplate repo.

I've checked this repo out and followed the instructions, running make install then make generate.

When running go main.go run the command errors out with this message:

build github.com/johanbrandhorst/grpc-gateway-boilerplate: cannot find module for path embed

Do you have any idea what could be happening here?

Can I also use grpc-web?

I'm trying to figure out how I would ALSO be able to open up a way for the mux to grab http 1.1 requests that are sendt via grpc-web.

It's not an issue, but I'm asking for some help, even for a good place to gather wisdom from.

See grpc-web:

grpcServer := grpc.Server()
wrappedGrpc := grpcweb.WrapServer(grpcServer)
tlsHttpServer.Handler = http.HandlerFunc(func(resp http.ResponseWriter, req *http.Request) {
    if wrappedGrpc.IsGrpcWebRequest(req) {
	    wrappedGrpc.ServeHTTP(resp, req)
    }
    // Fall back to other servers.
    http.DefaultServeMux.ServeHTTP(resp, req)
})

I'm going to be trying it soon, but I'm still working on some architecture, and now I realize this has to be possible but I don't know how yet.

Fix CI issues after merging PR #43

Make CI not RIP, #43 (comment)

How to use w/ Java Server

Hi, when I run the command for a standalone server I get a transient failure message. I'm kind of confused how to incorporate my own server, I have the address/port that the server is running on but I don't see how to get the gateway to point to it. Any help would be great thanks!

Incompatibility with the new Go ProtoReflect API

Hi - great project! Unfortunately, I'm hitting a blocker when I try to get your project up and running:

$ go run main.go
go: finding golang.org/x/net v0.0.0-20191002035440-2ec189313ef0
# github.com/johanbrandhorst/grpc-gateway-boilerplate/proto
proto/example.pb.gw.go:45:2: cannot use msg (type *User) as type protoreflect.ProtoMessage in return argument:
	*User does not implement protoreflect.ProtoMessage (missing ProtoReflect method)
proto/example.pb.gw.go:62:2: cannot use msg (type *User) as type protoreflect.ProtoMessage in return argument:
	*User does not implement protoreflect.ProtoMessage (missing ProtoReflect method)
proto/example.pb.gw.go:192:104: cannot use *User value as type protoreflect.ProtoMessage in return argument:
	*User does not implement protoreflect.ProtoMessage (missing ProtoReflect method)

It seems like this may be an issue with the new Go API for Protocol Buffers? I'm not sure if this is a version incompatibility issue with the versions specified in go.mod or if I'm perhaps using the wrong version of protoc?

$ protoc --version
libprotoc 3.11.2

Any thoughts would be very much appreciated!

Use without TLS

Can I run this without TLS?

Listen on both https and http?

Can i listen both on https and http?

Cannot use this repo as a GitHub repo template

We cannot use this repo as a template as statik/statik.go has 13.7MB in this repo as of 2020-11-04, which was recently introduced in #17.

File size	before #17 (= after #14)	after #17
`statik/statik.go`	6.8MB	13.7MB

Anyone can reproduce this by starting with Use this template button to see the following error:

We're sorry, something went wrong.
We were unable to clone johanbrandhorst/grpc-gateway-boilerplate's contents into {username,orgname}/{reponame}. The template you used includes files that are larger than 10 megabytes. Please ask johanbrandhorst to remove those files from the template and try again.

cf. https://github.com/education/classroom/issues/2521

updating to new buf manifest/config versions

First off I'd like to thank you for your awesome work, this repository has been an incredibly valuable source for learning how to structure a gRPC project in Go that uses gRPC-gateway.

I started writing my own template last year to add a few more things that I wanted to be figured out when I want to write a new service and it can be found in this repository on gitlab (it's also mirrored here on github).

Currently, my buf.yaml and buf.gen.yaml look a lot like yours and there is also wouldbe-buf.work.yaml because it currently doesn't work if you try to upgrade or if you just follow the steps in the official tour.

This led me to spend many evenings trying to troubleshoot it until I read a blog post that provided just enough details to figure out the issue.
In this commit on a feature branch I discovered that there is indeed a way to upgrade to it although it's less than ideal.

In rough order:

In each directory holding .proto files, put a simple buf.yaml with the deps key and then run buf mod update to create the lock file
If you're using v1, v2 and so on for different versions of the API, you need to do the above step seemingly for all directories until the repo root but I haven't done extensive testing. I had to do it in my protos/ directory that has two subdirectories/packages called v1 and v2
At the root of the project, buf.work.yaml can be just

version: v1
directories:
  - proto

Again at the root of the project, buf.yaml doesn't need the build key so it can just have the necessary name, version and deps, of course with version going from v1beta1 to v1 (v1 is where build and consequently build.root was removed)
Finally, run buf mod update at the root and then buf generate which shouldn't result in any issues

That's what worked for me, I hope this helps somewhat in case you were holding back from upgrading due to the inability for buf to pull in .proto dependencies or generate files properly.
Let me know if there is any additional information I can provide in case you wish to update the way buf stuff is handled, otherwise feel free to close the issue, I just wanted to share my experience dealing with this problem and what I did to fix it.