gRPC

Introduction

gRPC is a framework for client/server communication.

There are four communication patterns a gRPC service can implement:

• request / reply

• server streaming

• client streaming

• server and client streaming

The service declares the communication patterns in a protocol buffer file. The gRPC tool-chain generates code from this file, and your application implements the behavior as necessary.

Here's a sample .proto service definition.

syntax = "proto3";

service HelloService {
  // request / reply
  rpc SayHello(HelloRequest) returns (HelloResponse);
  
  // server streaming
  rpc LotsOfReplies(HelloRequest) returns (stream HelloResponse);
  
  // client streaming
  rpc LotsOfGreetings(stream HelloRequest) returns (HelloResponse);
  
  // server and client streaming
  rpc BidiHello(stream HelloRequest) returns (stream HelloResponse);
}

message HelloRequest {
  string greeting = 1;
}

message HelloResponse {
  string reply = 1;
}

message MessageRequest {
  string body = 1;
}

message MessageResponse {
  string body = 1;
}

You can find a full tutorial here.

Request / Reply

Server

The server implementation for this method must receive a context and request reference, and return a response reference and an error value.

type Robot {}

func (i *Robot) SayHello(ctx context.Context, *pb.HelloRequest) (*pb.HelloResponse, error) {
  return nil, fmt.Errorf("not implemented")
}

Client

Generate a client and send a request reference. Expect a response reference and an error value in return -- note that either of the response or the error value may be nil.

package main

import (
	"log"
	pb "gitlab.com/1ijk/pattern-library/grpc"
)

func main() {
	conn, err := grpc.Dial(*serverAddr, opts...)
	if err != nil {
		log.Fatalln(err)
	}
	defer conn.Close()

	client := pb.NewHelloServiceClient(conn)

	reply, err := client.SayHello(&pb.HelloRequest{
		Body: "Hi there!",
	})
	if err != nil {
		log.Fatalln(err)
	}
	
	if reply == nil {
		log.Fatalln("got empty reply from server")
	}
	
	log.Println(reply.GetBody())
}

There's a bunch of boilerplate to setup the main function and basic gRPC network connection; the important part is here:

	client := pb.NewHelloServiceClient(conn)

	reply, err := client.SayHello(&pb.HelloRequest{
		Body: "Hi there!",
	})