rpc

README

Go Language Application Framework

This respository contains remote procedure call (RPC) and service discovery modules for gopi. It supports gRPC and mDNS at present. This README guide will walk you though:

• Satisfying dependencies
• Building the helloworld service and client
• Understanding how to use an existing client in your application
• Generating a protocol buffer file for your service
• Creating a new service and client

Please also see documentation for:

• Protocol Buffers
• gRPC

Introduction

A "microservice" is a server-based process which can satisfy remote procedure calls, by accepting requests, processing the information within the service, and providing a response. A "simple" microservice might provide a single response to a request, a more complicated version will accept requests in a "stream" and may provide responses similarly in a "stream".

Protocol Buffers are an attractive mechanism for defining a schema for this request and response, and can generate both the client and server code programmatically in many languages using a compiler. The Google gRPC project is a useful counterpart for the compiler, providing supporting libraries, but there are others such as Twerp which can be used to provide a more traditional REST-based interface on compiling the protocol buffer code.

When you have your service running on your network, how do other processes discover it? This is where the discovery mechanisms come into play. For local area networks, discovery by DNS provides an easy mechansism, specifically using multicast DNS and the DNS-SD protocol. For cloud environents, service registration and discovery through services like Consul.

Dependencies

It is assumed you're using either a MacOS or Debian Linux machine. For MacOS, you should be using the Homebrew Package Manager:

bash# brew install protobuf
bash# go get -u github.com/golang/protobuf/protoc-gen-go

For Debian Linux:

bash# sudo apt install protobuf-compiler
bash# sudo apt install libprotobuf-dev
bash# go get -u github.com/golang/protobuf/protoc-gen-go

You can then use the protoc compiler command with the gRPC plugin to generate golang code for client and server.

The "helloworld" service

As an example, the Greeter service provides a call SayHello which takes a name parameter and returns a greeting message. The definition of the service is available in the folder rpc/protobuf/helloworld.proto:

package gopi;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

message HelloRequest {
  string name = 1;
}
message HelloReply {
  string message = 1;
}

The fully qualified name of the service is gopi.Greeter. The golang code to construct the client and service can be generated with the make protobuf command:

bash% make protobuf
go generate -x ./rpc/...
protoc helloworld/helloworld.proto --go_out=plugins=grpc:.

This will create the generated client and server code in the file rpc/protobuf/helloworld.pb.go. There are some other services defined in the rpc/protobuf folder:

• gopi.Version returns version numbers of the running service, service and host uptime.
• gopi.Discovery returns service records for any discovered and registered services on the local area network.

The make protobuf command generates the client and server code for these as well. In order to generate the helloworld client and service binaries, use the following commands:

bash% make helloworld-service
bash% make helloworld-client

You can run the helloworld service with unencrypted requests and responses:

bash% helloworld-service -rpc.port 8080 -verbose
[INFO] Waiting for CTRL+C or SIGTERM to stop server

Then to communicate with the service, use the following command in a separate terminal window:

bash% helloworld-client -addr localhost:8080 -rpc.insecure

You can use encrypted communications if you provide an SSL key and certificate. In order to generate a self-signed certificate, use the following commands, replacing DAYS, OUT and ORG with appropriate values:

bash% DAYS=99999
bash% OUT="${HOME}/.ssl"
bash% ORG="mutablelogic"
bash% install -d ${OUT} && openssl req \
  -x509 -nodes \
  -newkey rsa:2048 \
  -keyout "${OUT}/selfsigned.key" \
  -out "${OUT}/selfsigned.crt" \
  -days "${DAYS}" \
  -subj "/C=GB/L=London/O=${ORG}"

Then the following commands are used to invoke the service:

bash% helloworld-service -rpc.port 8080 \
  -rpc.sslkey ${OUT}/selfsigned.key -rpc.sslcert  ${OUT}/selfsigned.crt \
  -verbose
[INFO] Waiting for CTRL+C or SIGTERM to stop server

You can then drop the -rpc.insecure flag when invoking the client.

Using a client in your own application

TODO

Generating a protocol buffer file for your service

TODO

Creating a new service and client

TODO

Documentation

Index

• type DiscoveryType
• type Duration
  • func (this *Duration) MarshalJSON() ([]byte, error)
  • func (this *Duration) UnmarshalJSON(data []byte) error
• type Event
  • func NewEvent(source gopi.Driver, type_ gopi.RPCEventType, service gopi.RPCServiceRecord) *Event
  • func (*Event) Name() string
  • func (this *Event) ServiceRecord() gopi.RPCServiceRecord
  • func (this *Event) Source() gopi.Driver
  • func (this *Event) String() string
  • func (this *Event) Type() gopi.RPCEventType
• type ServiceRecord
  • func NewServiceRecord() *ServiceRecord
  • func (this *ServiceRecord) AppendIP4(rr *dns.A)
  • func (this *ServiceRecord) AppendIP6(rr *dns.AAAA)
  • func (this *ServiceRecord) Expired() bool
  • func (this *ServiceRecord) Host() string
  • func (this *ServiceRecord) IP4() []net.IP
  • func (this *ServiceRecord) IP6() []net.IP
  • func (this *ServiceRecord) Key() string
  • func (this *ServiceRecord) Name() string
  • func (this *ServiceRecord) Port() uint
  • func (this *ServiceRecord) Service() string
  • func (this *ServiceRecord) SetPTR(zone string, rr *dns.PTR)
  • func (this *ServiceRecord) SetSRV(rr *dns.SRV)
  • func (this *ServiceRecord) SetTXT(rr *dns.TXT)
  • func (s *ServiceRecord) String() string
  • func (this *ServiceRecord) TTL() time.Duration
  • func (this *ServiceRecord) Text() []string
  • func (this *ServiceRecord) Timestamp() time.Time

Types

type DiscoveryType

type DiscoveryType uint

DiscoveryType is either DNS (using DNS-SD) or DB (using internal database)

const (
	DISCOVERY_TYPE_NONE DiscoveryType = 0
	DISCOVERY_TYPE_DNS  DiscoveryType = 1
	DISCOVERY_TYPE_DB   DiscoveryType = 2
)

type Duration

type Duration struct {
	Duration time.Duration
}

Duration type to read and write JSON better

func (*Duration) MarshalJSON

func (this *Duration) MarshalJSON() ([]byte, error)

func (*Duration) UnmarshalJSON

func (this *Duration) UnmarshalJSON(data []byte) error

type Event

type Event struct {
	// contains filtered or unexported fields
}

RPCEvent implementation

func NewEvent

func NewEvent(source gopi.Driver, type_ gopi.RPCEventType, service gopi.RPCServiceRecord) *Event

func (*Event) Name

func (*Event) Name() string

Return name of event

func (*Event) ServiceRecord

func (this *Event) ServiceRecord() gopi.RPCServiceRecord

Return the service record

func (*Event) Source

func (this *Event) Source() gopi.Driver

Return source of event

func (*Event) String

func (this *Event) String() string

func (*Event) Type

func (this *Event) Type() gopi.RPCEventType

Return the type of event

type ServiceRecord

type ServiceRecord struct {
	Key_     string    `json:"key"`
	Name_    string    `json:"name"`
	Host_    string    `json:"host"`
	Service_ string    `json:"service"`
	Port_    uint      `json:"port"`
	Txt_     []string  `json:"txt"`
	Ipv4_    []net.IP  `json:"ipv4"`
	Ipv6_    []net.IP  `json:"ipv6"`
	Ts_      time.Time `json:"ts"`
	Ttl_     *Duration `json:"ttl"`
	Local_   bool      `json:"local"`
}

RPCServiceRecord implementation

func NewServiceRecord

func NewServiceRecord() *ServiceRecord

func (*ServiceRecord) AppendIP4

func (this *ServiceRecord) AppendIP4(rr *dns.A)

func (*ServiceRecord) AppendIP6

func (this *ServiceRecord) AppendIP6(rr *dns.AAAA)

func (*ServiceRecord) Expired

func (this *ServiceRecord) Expired() bool

func (*ServiceRecord) Host

func (this *ServiceRecord) Host() string

func (*ServiceRecord) IP4

func (this *ServiceRecord) IP4() []net.IP

func (*ServiceRecord) IP6

func (this *ServiceRecord) IP6() []net.IP

func (*ServiceRecord) Key

func (this *ServiceRecord) Key() string

func (*ServiceRecord) Name

func (this *ServiceRecord) Name() string

func (*ServiceRecord) Port

func (this *ServiceRecord) Port() uint

func (*ServiceRecord) Service

func (this *ServiceRecord) Service() string

func (*ServiceRecord) SetPTR

func (this *ServiceRecord) SetPTR(zone string, rr *dns.PTR)

func (*ServiceRecord) SetSRV

func (this *ServiceRecord) SetSRV(rr *dns.SRV)

func (*ServiceRecord) SetTXT

func (this *ServiceRecord) SetTXT(rr *dns.TXT)

func (*ServiceRecord) String

func (s *ServiceRecord) String() string

func (*ServiceRecord) TTL

func (this *ServiceRecord) TTL() time.Duration

func (*ServiceRecord) Text

func (this *ServiceRecord) Text() []string

func (*ServiceRecord) Timestamp

func (this *ServiceRecord) Timestamp() time.Time