ypgrpc-go-app Quick Start Guide

As in many RPC systems, gRPC is based around the idea of defining a service, specifying the methods that can be called remotely with their parameters and return types. On the server side, the server implements this interface and runs a gRPC server to handle client calls.

The ypgrpc-go-app subsystem provides an unified place where all the interfaces can be implemented and runs a gRPC server to handle client calls.

The first step when working with protocol buffers is to define the structure for the data to serialize in a .proto file

this is an ordinary text file with a .proto extension.

Protocol buffer data is structured as messages, where each message is a small logical record of information containing a series of name-value pairs called fields.

The next step is to define gRPC services in ordinary .proto files, with RPC method parameters and return types specified as protocol buffer messages. Refer to $HOME/go/src/ypgrpc/examples/helloworld/helloworld.proto for an example.

/* The greeting service definition */
service Greeter {
  /* Sends a greeting */
  rpc SayHello (HelloRequest) returns (HelloReply) {}

  /* Sends another greeting */
  rpc SayHelloAgain (HelloRequest) returns (HelloReply) {}
}

/* The request message containing the user's name */
message HelloRequest {
  string name = 1;
}

/* The response message containing the greetings */
message HelloReply {
  string message = 1;
}

ypgrpc-go-app Application Helloworld Example

Run the server with --with-grpc=true CLI parameter as follows:

mydir> sudo netconfd-pro --log-level=debug4 --with-grpc=true --fileloc-fhs=true

The example code of ypgrpc-go-app after installation should be copied to $HOME/go/src/ypgrpc and example Service implementation copied to $HOME/go/src/ypgrpc/examples.

In order to run the example application:

Change to the example directory:
```
> cd $HOME/go/src/ypgrpc
```

Compile and execute the ypgrpc-go-app code:

ypgrpc> go run ypgrpc-go-app.go --log-level=debug --fileloc-fhs --insecure --proto=helloworld --protopath=$HOME/protos

Run the client application:

The gRPC client applications are out of the scope of this document. In this example grpc-client-cli tool is used:

> grpc-client-cli --proto $HOME/protos/helloworld.proto localhost:50830
? Choose a service: helloworld.Greeter
? Choose a method: SayHello
Message json (type ? to see defaults): {"name":"An example name"}
{
  "message": "Hello An example name"
}

After the request is sent the gRPC server will run the corresponding callback and reply to the client request with a message as defined in the .proto files. The ypgrpc-go-app application log may look as follows:

ypgrpc_server: Starting to serve

HelloRequest:{
  "name": "An example name"
}

Update ypgrpc-go-app Services

The gRPC service is defined using the following . proto file.

/* The greeting service definition */
service Greeter {
  /* Sends a greeting */
  rpc SayHello (HelloRequest) returns (HelloReply) {}

  /* Sends another greeting */
  rpc SayHelloAgain (HelloRequest) returns (HelloReply) {}
}

/* The request message containing the user's name */
message HelloRequest {
  string name = 1;
}

/* The response message containing the greetings */
message HelloReply {
  string message = 1;
}

The .proto file will generate both client and server stub code that have a SayHello() RPC method, that takes a HelloRequest parameter from the client, and returns a HelloReply from the server.

To add a service definition, open $HOME/go/src/ypgrpc/examples/helloworld/helloworld.proto and add a new SayHelloOneMore() method, with the same request and response types:

/* The greeting service definition */
service Greeter {
  /* Sends a greeting */
  rpc SayHello (HelloRequest) returns (HelloReply) {}

  /* Sends another greeting */
  rpc SayHelloAgain (HelloRequest) returns (HelloReply) {}

  /* Sends another greeting */
  rpc SayHelloOneMore (HelloRequest) returns (HelloReply) {}
}

/* The request message containing the user's name */
message HelloRequest {
  string name = 1;
}

/* The response message containing the greetings */
message HelloReply {
  string message = 1;
}

Regenerate gRPC Code

Before you can use the new service method, you need to recompile the updated .proto file.

In the examples directory, run the following command:

> cd $HOME/go/src/ypgrpc/examples
> protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. \
   --go-grpc_opt=paths=source_relative helloworld/helloworld.proto

This will regenerate the helloworld/helloworld.pb.go and helloworld/helloworld_grpc.pb.go files, which contain:

Code for populating, serializing, and retrieving HelloRequest and HelloReply message types
Generated server stub code to integrate into ypgrpc-go-app application

Server Code will be used by ypgrpc-go-app application that will register this Service and Methods and where the instrumentation will be done.

Update ypgrpc-go-app

After the regenerated server code is done, it can be implemented, called and integrated into the ypgrpc-go-app application.

Open $HOME/go/src/ypgrpc/ypgrpc-go-app.go and add the following function to it:

/* SayHelloOneMore implements helloworld.GreeterServer */
func (s *helloworldServer) SayHelloOneMore (ctx context.Context,
                                            in *helloworld.HelloRequest) (
    *helloworld.HelloReply,
     error) {

    log.Log_info("\n\nHelloRequest:")
    log.Log_dump_structure(in)

    return &helloworld.HelloReply{
        Message: "Say Hello OneMore" + in.GetName(),
    }, nil
}

Run Updated ypgrpc-go-app

Run the netconfd-pro server and the ypgrpc-go-app application:

Run the netconfd-pro server:

mydir> sudo netconfd-pro --log-level=debug4 --with-grpc=true --fileloc-fhs=true

Change to the example directory:
```
> cd $HOME/go/src/ypgrpc
```

Run the updated ypgrpc-go-app application:

ypgrpc> go run ypgrpc-go-app.go --log-level=debug --fileloc-fhs --insecure \
   --proto=helloworld --protopath=$HOME/protos

Run the client application:

The gRPC client applications are out of the scope of this document. In this example grpc-client-cli tool is used:

> grpc-client-cli --proto $HOME/protos/helloworld.proto localhost:50830
  ? Choose a service: helloworld.Greeter
  ? Choose a method: SayHelloOneMore

  Message json (type ? to see defaults): {"name":" An example name"}
  {
    "message": "Say Hello OneMore An example name"
  }

After the request is sent the gRPC server will run the corresponding callback and reply to the client request with a message as defined in the .proto files. The ypgrpc-go-app application log may look as follows:

ypgrpc_server: Starting to serve

HelloRequest:{
  "name": " An example name"
}