gokit-gen

README

gokit-gen

Provide a .proto file, get a go-kit generated package, a boilerplate package for your microservices.

Yes, you will have to complete a lot of details in tests, and, yes there is a lot to be improved in this project.

It will generate:

• domain.go - decoupling the Service from Transport layer
• endpoints.go - two transports (HTTP and gRPC) have two methods of sending requests to the same endpoint
• grpc_client.go - a GRPC client for the server - used for tests AND in other micro-services
• grpc_server.go - the GRPC server
• http_client.go - a HTTP client for the server - used for tests only
• http_server.go - serving HTTP to the outside world
• repository.go - a possible repository interface and implementation
• service.go - the business logic holder - it's coupled to repository interface, just in case you need it
• transform.go - all sort of transformers from protobuf to domain objects and back
• some tests

If you need streaming, it knows how to generate all three kinds :

• half duplex - server streams, client make initial request
• reverse half duplex - client streams, server speaks the final response
• full duplex - both client and server are streaming away

install

go get -u github.com/badu/gokit-gen/cmd/gokit-gen

parameters

1. proto file - can be absolute or relative

2. templates folder ("default" uses default templates) - can be absolute or relative

3. full package, for imports in generated tests

4. optional, deployment folder - can be absolute or relative

Declaring proto options

Prerequisite : make sure you have grpc-gateway local (run go get github.com/grpc-ecosystem/grpc-gateway )

1. import import "google/protobuf/descriptor.proto"; in proto file

2. declare your option as in:

extend google.protobuf.MethodOptions {
	string security = 50001;
}

1. use the option in your rpc definition, as in:

	rpc GetFeature (Point) returns (Feature) {
		option (security) = "jwt";
	}

1. in template, you can check for an option like this:

{{ if .Options.NamedValueEq "security" "jwt" }}
	<place_go_code_here>
{{ end }}

1. Generate your Go from protofile as in below example:

protoc -I/usr/local/include -I. -I$GOPATH/src -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis --go_out=plugins=grpc:. *.proto

Note : using HTTP without defining your own options, would imply the following:

Having the following message declaration (attention : order of fields declared in Point message matters for http GET route)

message Point {
	int32 latitude = 1;
	int32 longitude = 2;
}

Remember that only these HTTP verbs are allowed

A. import import "google/api/annotations.proto"

B. in rpc definition put the option:

	rpc GetFeature (Point) returns (Feature) {
		option (google.api.http) = { get: "/v1/feature/{latitude}/{longitude}" };
	}
	
	rpc CreateFeature(Feature) returns (Feature){
		option (google.api.http) = {
          post: "/v1/feature"
          body: "shelf"
        };
    }

Updating a proto file from here

Updating A Message Type

If an existing message type no longer meets all your needs – for example, you'd like the message format to have an extra field – but you'd still like to use code created with the old format, don't worry! It's very simple to update message types without breaking any of your existing code. Just remember the following rules:

Don't change the field numbers for any existing fields.

If you add new fields, any messages serialized by code using your "old" message format can still be parsed by your new generated code. You should keep in mind the default values for these elements so that new code can properly interact with messages generated by old code. Similarly, messages created by your new code can be parsed by your old code: old binaries simply ignore the new field when parsing. See the Unknown Fields section for details.

Fields can be removed, as long as the field number is not used again in your updated message type. You may want to rename the field instead, perhaps adding the prefix "OBSOLETE_", or make the field number reserved, so that future users of your .proto can't accidentally reuse the number.

int32, uint32, int64, uint64, and bool are all compatible – this means you can change a field from one of these types to another without breaking forwards- or backwards-compatibility. If a number is parsed from the wire which doesn't fit in the corresponding type, you will get the same effect as if you had cast the number to that type in C++ (e.g. if a 64-bit number is read as an int32, it will be tru~~~~ncated to 32 bits).

sint32 and sint64 are compatible with each other but are not compatible with the other integer types.

string and bytes are compatible as long as the bytes are valid UTF-8.

Embedded messages are compatible with bytes if the bytes contain an encoded version of the message.

fixed32 is compatible with sfixed32, and fixed64 with sfixed64.

enum is compatible with int32, uint32, int64, and uint64 in terms of wire format (note that values will be truncated if they don't fit). However be aware that client code may treat them differently when the message is deserialized: for example, unrecognized proto3 enum types will be preserved in the message, but how this is represented when the message is deserialized is language-dependent. Int fields always just preserve their value.

Changing a single value into a member of a new oneof is safe and binary compatible. Moving multiple fields into a new oneof may be safe if you are sure that no code sets more than one at a time. Moving any fields into an existing oneof is not safe.

Using ANTLR

This is not needed, just in case you want to alter grammar file

1. Download ANTLR

Change dir to /usr/local/lib and run:

sudo curl -O https://www.antlr.org/download/antlr-4.8-complete.jar

1. Create alias

Note : Might want to save this command to .bashrc

alias antlr='java -jar /usr/local/lib/antlr-4.8-complete.jar'

1. Run generator

Inside /pkg/antlr folder run :

antlr -Dlanguage=Go -o parser antlr.g4