In this section we'll be going over how you can quickly get started with fRPC^[1], from defining your message types in a proto3^[2] file, to writing your first server and client.

We'll be building a simple echo service that will echo back the message it receives, and later on we'll also show how you can use the Frisbee framework itself to build a more complex PUB/SUB^[3] service.

Installation

To get started with fRPC^[1], you'll need to make sure you have Go and the protoc compiler installed. Then, you'll need to install the protoc-gen-go-frpc protoc plugin^[4] which we will use to generate the server and client code.

Prerequisites

• Go - fRPC works with Go version 1.18 or later. For installation instructions see Go's Getting Started Guide.
• Protocol Buffer Compiler (protoc) - fRPC works with protoc version 3. For installation instructions see the Protoc Getting Started Guide.

If you're using MacOS and have Brew installed, you can use brew install go to install Golang, and brew install protoc to install the protoc compiler.

Install the fRPC Plugin

To install the protoc-gen-go-frpc plugin, you'll first need to make sure that your $GOBIN environment variable is set and available in your system path. See the Go Environment Variables page for more information, but in general, you can do this by adding the following to your ~/.bashrc file:

sh

To install the protoc-gen-go-frpc plugin itself, you'll need to run the following command:

bash

This will install the protoc-gen-go-frpc plugin into your $GOBIN directory where it will be available for use by the protoc compiler.

You can check that the plugin is installed and available by running the following command:

bash

Create a Proto3 File

Now that we have the prerequisites and the protoc-gen-go-frpc plugin installed, we can start writing our echo service. Let's start by creating a directory to house our project:

bash

Now we'll create an echo.proto file and define our message types:

protobuf

You can see that we've defined two message types, one for the Request and one for the Response.

Next, we will define a new EchoService in our proto3 file. This tells the compiler that we want to generate a server and client for this service.

protobuf

And with that you should be ready. Next we'll start the protoc compiler to generate our fRPC server and client.

Generate the Server and Client

Let's run the following command to generate the server and client code:

bash

This command tells the protoc compiler to generate the server and client code for us and by specifying the --go-frpc_out flag, we're implicitly specifying that we want to use the protoc-gen-go-frpc plugin.

If we wanted to be more explicit, we could have run the following command:

bash

These commands should have generated a new folder at ~/frpc/echo, which contains an echo.frpc.go file containing the server and client code. Within that file, you'll find the following interface:

go

All we have left to do is implement the EchoService interface with our server-side logic, and pass that into the server. The generated library will then be able to handle everything else for us.

Setting up the Server

To set up our server, we simply need to implement the EchoService interface and then start the server. We'll start by creating a new server/main.go file in our ~/frpc directory:

go

As you can see we've created a new struct called svc and implemented the EchoService interface by creating a new function called Echo which takes a context.Context and an *echo.Request object. We aren't really using the context in this example so we just ignore that and instead return an *echo.Response object with the same message as the request.

Now we can implement the server itself:

go

This additional main function runs when the server starts up, and passes in our svc struct to the generated echo.NewServer() function. It then binds the server to port :8080 and starts listening for connections.

We're passing in nil for both the *tls.Config and logging parameters in the generated echo.NewServer() function because we don't want to use TLS or logging in this example.

Setting up the Client

To set up our client, we don't need to implement any additional logic, but we do need to create a new client/main.go file in our ~/frpc directory:

go

Here, we're creating a new echo client using our generated echo.NewClient() function. Then, we're passing in the address of the server we want to connect to. But we're not actually sending any requests to the server yet.

To do that, we can write a simple look to send a request to the server every second and then print out the response:

go

The above loop registers a stop channel to receive a signal when the user hits Ctrl+C, and then starts sending a request to the server every second.

And that's it! We've now set up a simple echo client that can send requests to our server and print out the response.

We were able to use a simple proto3 file to define our request and response objects, and all we had to do was implement the EchoService interface. Everything else was handled for us by fRPC.

The complete code for this example is available in the frpc-echo-example repository on Github.

Next Steps

Now that we've seen how easy it is to use fRPC, we recommend you check out our benchmarks pages to learn more about how fRPC fares against other RPC frameworks.

If you want to learn more about how fRPC works under the hood, you can check out our fRPC Concepts page, or our technical reference.

Finally, if you'd like to learn how to use Frisbee (the underlying transport mechanism for fRPC) to implement your own messaging protocol that's fast and performant, you can check out the frisbee-go Github repository.

If you need any help or have any feedback about Frisbee or fRPC, please to check out our Discord Community! Our team would love to hear your thoughts and understand how you're planning on using fRPC, and we're always happy to help!