Before diving into gRPC descriptors and it’s implementation in kalix let’s get a brief understanding of gRPC so,
What is gRPC?
gRPC is an open-source Remote Procedure Call (RPC) framework developed by Google. It’s modern, fast, efficient, and built on top of HTTP/2, low latency supports streaming, is language-independent, and makes it super easy to plug in authentication, load balancing, logging, and monitoring.
Now the question is how you can implement it?
So at the core of the gRPC you have to define the protocol buffers which contain all your messages and services. The rest of the gRPC code is generated for you and you’ll have to provide an implementation for it.
You just have to define one .proto file and it will work for over 12 programming languages and it will work for both server and client.
gRPC Descriptor
gRPC descriptor is just the integration server representation of the gRPC proto file. The elements associated with the gRPC descriptor corresponding to the service definitions, methods, and messages in the proto file.
Moving forward let’s see how we can define the descriptor in the KALIX
Implementing gRPC descriptors in KALIX
As stated above the gRPC descriptor in KALIX, as well as implemented in the proto file viz Protocol Buffer Language. You just have to provide the command messages, data associated with Entities, and events in .proto files and that’s it the rest of the work is then handled by the gRPC compiler, which will generate the server and client-side code.
The above paragraph must have given you a sense of relief as now you can just concentrate on your business logic rather than worrying about your server-side problems, let’s visualize it syntactically in the .proto file:
API Proto File
The service proto implementation is done in two ways the first part we define the service and then we define the messages
Service
The API proto file defines as how does the entity will look like to the outside world. The syntax for this is quite simple protobuff syntax, you start with defining the version of Protocol Buffer syntax which is then followed by your imports and then the name of your package.
The best part starts now, you have to define the main service which is implemented as shown below
It starts with a service name by which you’ll be referring it, then we implement the kalix.codegen which is responsible for generating all the stubs for your entity/service and corresponding tests, as well as an abstract class for your implementation to extend.
After this, you specify which type of entity you want to implement in the above example we’ve implemented a value entity in which we’ve to include fields as follows:
- name
- entity_type: Which specifies what kind of entity you wanna implement.
- state This is basically the domain object which holds the state.
This was all about the service, now you have to define the API from the service which is done using RPC(Remote Procedure Call) as follows:
The RPC syntax is quite simple you start with the API name after that you pass the object name (viz passed as a command) the naming convention is totally up to you. In the above service, the optional transcoding of the service to bind the various endpoints to HTTP is highlighted with annotations.
One thing to note is that since the above service is the POST call the return type is mentioned as empty, but for the GET call you’ll have to define the response for it.
Message
The commands used in RPC calls are defined using messages which are associated using the identity key and Entity so that Kalix can identify which entity the message is for. For example
The command used Customer is defined as follows:
Here you’ll see that customer_id is kept as a compound key. The requirement here is that all the entities at the API level needed to be defined with (kalix.field).entity_key & it has to be the same for all the commands.
That’s it for the service. Now we’ll see how the Domain file is defined.
Domain Proto File
A domain defines how does your data look like from the inside. So for the example mentioned below, we have created only one object since we have taken the example of the value entity.
The customer and address are the entity state which is defined as messages.
Conclusion
Thank you for making it to the end. This was all about how you can implement the gRPC descriptors in the kalix. The above example mentioned is for the value entities, you can find more about different types of entities by clicking here.
If you like my writing style please do check out my more blogs.
Reference
Kalix documentation -> https://docs.kalix.io/java/writing-grpc-descriptors-protobuf.html
