Jeffrey Carpenter

In the first post in this series, I described the KillrVideo reference application and my motivation for creating a new implementation of the microservices tier for KillrVideo in Python.

In this post, I’d like to start tracing the development of this Python application in somewhat chronological order. So, here goes…

<code>// Request to create a new user message CreateUserRequest { 
&nbsp; &nbsp;killrvideo.common.Uuid user_id = 1; 
&nbsp; &nbsp;string first_name = 2; 
&nbsp; &nbsp;string last_name = 3; 
&nbsp; &nbsp;string email = 4; 
&nbsp; &nbsp;string password = 5; 
} 
// Response when creating a new user message CreateUserResponse {} </code>

<h2>Where to start?</h2>

Remember that this Python implementation is just the microservice tier — meaning that there is an existing webapp that sits on top of these services which is already implemented (<a href="https://github.com/killrvideo/killrvideo-web">killrvideo-web</a>). And, there is an existing database schema that the services will use (<a href="https://github.com/killrvideo/killrvideo-data">killrvideo-data</a>)

So, I decided to start building the application from the “outside-in”. This means creating the code that defines the interfaces by which the services would be invoked — in this context that code is the GRPC stubs. One advantage of starting with stubs is that I can begin plugging in the Python services to the rest of the KillrVideo system as quickly as possible, including the <a href="https://github.com/killrvideo/killrvideo-integration-tests">killrvideo-integration-tests</a> which we’ll dive into in a future post.

<img alt="KillrVideo Python GRPC Logo" data-entity-type="file" data-entity-uuid="f5905de5-f06f-4649-af86-ca28d4284aa7" src="https://www.datastax.com/sites/default/files/inline-images/1_j-lvdlR6on0iJCMslYKsRw.png" />

<h2>Why GRPC?</h2>

Taking a step back, I need to discuss why Google Remote Procedure Call (GRPC) was chosen. The really simple answer is that we’ve defined the standard service interfaces for KillrVideo using GRPC.

There are certainly many options for exposing service interfaces, and the history of the IT industry is littered with many approaches that have gained and then lost popularity over the years (I remember <a href="https://corba.org/">CORBA</a> with a lot more sympathy than the awfulness of defining “web services” with XML-based formats such as <a href="https://www.w3.org/TR/2001/NOTE-wsdl-20010315">WSDL</a> and SOAP).

For modern cloud applications, the leaders these days seem to be:

<ul>
	<li>REST</li>
	<li>GRPC</li>
	<li>GraphQL</li>
</ul>

RESTful APIs have the advantage of being ubiquitous and probably the lowest barrier to define thanks to the availability of frameworks such as Spring. Unfortunately I find it challenging to enforce consistent semantics when you have more than a few RESTful APIs, and I’ve been a part of quite a few arguments about how to properly structure URL resource paths that probably weren’t worth the mental energy (“should the path be hotels/inventory, or inventory/hotels?” or “should we put the API version number in the path?”).

The main reason we didn’t choose to define RESTful APIs for KillrVideo services is due to our desire to provide service implementations in multiple languages — the difficulty of describing or enforcing common semantics across multiple language implementations

We ended up choosing GRPC as the way of defining service interfaces for KillrVideo. GRPC is more of a successor to the CORBA style model in which there’s an interface definition language (IDL), from which programming-language-specific stubs can be generated. This is a better fit for our polyglot implementation approach and has served us well so far.

<a href="https://graphql.org/">GraphQL</a> is an emerging standard for developing APIs that has a number of promising characteristics, most notably the ability for clients to specify exactly the information they are interested to a fine degree of control. Finer control like joining data and filtering was certainly possible previously in RESTful APIs using techniques like XPath, but the approach was pretty unwieldy and difficult to implement consistently.

The emerging best practice seems to be using GraphQL with in a web application tier as a way of exposing a server-side API that represents data in the way which is most useful to the client application. So GraphQL services are often higher-order services built on top of services that expose APIs using the techniques described above (REST, GRPC, etc.). We’ve actually started the process of rewriting <a href="https://github.com/killrvideo/killrvideo-web">killrvideo-web</a> using GraphQL, so that will be a fun topic to discuss in the future.

<h2>Defining the GRPC APIs</h2>

We define an interface for each service in the killrvideo-service-protos repository. The interfaces are defined a common repo so they can then be included or referenced in various language implementations.

<a href="https://github.com/KillrVideo/killrvideo-service-protos/blob/master/src/user-management/user_management_service.proto#L8-L13">KillrVideo/killrvideo-service-protos</a>

The Grpc service definitions for KillrVideo. Contribute to KillrVideo/killrvideo-service-protos development by creating…github.com

Here’s an example: the interface for the <a href="https://github.com/KillrVideo/killrvideo-service-protos/blob/master/src/user-management/user_management_service.proto"><code>UserManagementService</code></a>:

<code>// The service responsible for managing user information service UserManagementService { 
&nbsp; &nbsp;// Creates a new user 
&nbsp; &nbsp;rpc CreateUser(CreateUserRequest) returns (CreateUserResponse); </code>

<code>// Verify a user's username and password 
rpc VerifyCredentials(VerifyCredentialsRequest) 
&nbsp; &nbsp;returns (VerifyCredentialsResponse); </code>

<code>// Gets a user or group of user's profiles 
rpc GetUserProfile(GetUserProfileRequest) 
&nbsp; &nbsp;returns (GetUserProfileResponse); 
} </code>

Notice that each service operation is a remote procedure call (<code>rpc</code>) which in turn takes a single request parameter and returns a single response parameter. These are synchronous operations by definition. Here’s an example of what the request/response messages look like for the <code>CreateUser</code> operation:

<code>// Request to create a new user 
message CreateUserRequest { 
&nbsp; &nbsp;killrvideo.common.Uuid user_id = 1; 
&nbsp; &nbsp;string first_name = 2; 
&nbsp; &nbsp;string last_name = 3; 
&nbsp; &nbsp;string email = 4; 
&nbsp; &nbsp;string password = 5; 
} 
// Response when creating a new user message CreateUserResponse {} </code>

The <code>CreateUserRequest</code> looks straightforward — it includes simple types like string as well as a special type we’ve defined to represent a unique identifier — <code>killrvideo.common.UUID</code>. We’ve defined a UUID type within a common killrvideo namespace for use in our service interfaces, since GRPC (strangely) <a href="https://github.com/protocolbuffers/protobuf/issues/2224">does not define a common UUID type</a>.

You’ll also notice that although the&nbsp;<code>CreateUser</code>&nbsp;<cod> operation does not have a specific return value, we still define an empty return message <code>CreateUserResponse</code>.</cod>

It’s also worth noting that GRPC does support asynchronous message passing semantics. You can see an example “event” definition in the&nbsp; u<code>ser_management_events.proto</code>&nbsp;file. We’ll dig more into messaging in an upcoming post.

<h2>Generating GRPC stubs</h2>

Given service interfaces defined in GRPC, the next step is to create bindings in the chosen implementation language, in our case, Python. Leveraging some of the <a href="https://blog.codeship.com/using-grpc-in-python/">great tutorials</a> available, I figured out how to generate the stubs for multiple services. First I had to install the grpcio-<code>tools</code> package:

<code>$ pip install grpcio-tools </code>

Then I ran the generator to create the stubs. Note that the generator creates both client and server stubs.

<code>python -m grpc_tools.protoc -I. --python_out=../../../killrvideo --grpc_python_out=../../../killrvideo comments/*.proto common/*.proto ratings/*.proto search/*.proto statistics/*.proto suggested-videos/*.proto uploads/*.proto user-management/*.proto video-catalog/*.proto </code>

There was a bit of a trick to getting the generator to work because of the <code>.proto</code>&nbsp;files files being spread across multiple directories. I ended up having to name each of the directories including the directory containing the common type definitions.

The command above is preserved in the <code>generate-grpc-stubs.sh</code>&nbsp;script which I’ve included in the repository in case anyone should need to regenerate the stubs (for example, on an interface change).

<h2>Implementing the services</h2>

The next step is to begin to implement each of the services. For the initial implementation I chose to follow the pattern used in the other KillrVideo language implementations, which was to incorporate all of the service interfaces in a single application. This approach provides a lot of simplicity for running / deploying the services, but of course limits our ability to scale services independently, or even mix-and-match service implementations in different languages, something that is on the KillrVideo roadmap.

<h2>The servicer</h2>

If you examine one of the generated files such as <a href="https://github.com/KillrVideo/killrvideo-python/blob/master/killrvideo/user_management/user_management_service_pb2_grpc.py"><code>user_management_service_pb2_grpc.py</code></a>, you’ll see the server stub, which is a Python class that looks like this:

<code>class UserManagementServiceServicer(object): 
&nbsp; &nbsp;"""The service responsible for managing user information 
&nbsp; &nbsp;""" 
&nbsp; &nbsp;def CreateUser(self, request, context): 
&nbsp; &nbsp;"""Creates a new user 
&nbsp; &nbsp;""" 
&nbsp; &nbsp;context.set_code(grpc.StatusCode.UNIMPLEMENTED) 
&nbsp; &nbsp;context.set_details('Method not implemented!') 
&nbsp; &nbsp;raise NotImplementedError('Method not implemented!') 
... </code>

<h2>A subclass for GRPC server implementation</h2>

The generated code as set to indicate that each method is not implemented. So the task that is left for us is to implement the methods in the server stub. The best practice is actually to treat the generated stub as a base class and create a subclass to override the method implementations.

You can find my implementation of the Search Service in the <code>user_management_service_grpc.py</code> file.

<h2>Registering services with the GRPC server</h2>

The final step is to start a GRPC server and register our service with it. While I wish the GRPC generator had an option to generate a nice <code>main()</code> function for us to do this, it appears that you just need to copy some <a href="https://grpc.io/docs/tutorials/basic/python.html#starting-the-server">example code</a>. You can find the code that initiates all of the KillrVideo services in the main application file at the root of the module (<a href="https://github.com/KillrVideo/killrvideo-python/blob/master/killrvideo/__init__.py">__init__.py</a>):

<code>def serve(): 
&nbsp; &nbsp;# Initialize GRPC Server 
&nbsp; &nbsp;grpc_server = grpc.server(futures.ThreadPoolExecutor(max_workers=10)) 
&nbsp; &nbsp;# Initialize Services 
&nbsp; &nbsp;CommentsServiceServicer(grpc_server, &nbsp; CommentsService()) 
&nbsp; &nbsp;RatingsServiceServicer(grpc_server, RatingsService()) 
&nbsp; &nbsp;SearchServiceServicer(grpc_server, SearchService()) 
&nbsp; &nbsp;StatisticsServiceServicer(grpc_server, StatisticsService()) 
&nbsp; &nbsp;SuggestedVideosServiceServicer(grpc_server, SuggestedVideosService()) 
&nbsp; &nbsp;UserManagementServiceServicer(grpc_server, 
UserManagementService()) 
&nbsp; &nbsp;VideoCatalogServiceServicer(grpc_server, VideoCatalogService()) 
&nbsp; &nbsp;# Start GRPC Server 
&nbsp; &nbsp;grpc_server.add_insecure_port('[::]:' + _SERVICE_PORT) grpc_server.start() 
&nbsp; &nbsp;# Keep application alive 
&nbsp; &nbsp;try: 
&nbsp; &nbsp;&nbsp; &nbsp;while True: 
&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;time.sleep(_ONE_DAY_IN_SECONDS) 
&nbsp;except KeyboardInterrupt: 
&nbsp; &nbsp;&nbsp; &nbsp;grpc_server.stop(0) </code>

This code is a bit different from the example code referenced above in that it exposes multiple services on the same port, which is a perfectly acceptable approach for a simple reference application.

One of the things that you might have noticed in the code above is that I’m delegating the work of registering with the GRPC server to a separate constructor function for each of the service implementations. For example, the <code>user_management_service_grpc.py</code> file we find the constructor which actually performs the registration:

<code>class UserManagementServiceServicer( user_management_service_pb2_grpc.UserManagementServiceServicer): """Provides methods that implement functionality of the UserManagement Service.""" def __init__(self, grpc_server, user_management_service): self.user_management_service = user_management_service user_management_service_pb2_grpc.add_UserManagementServiceServicer_to_server(self, grpc_server) </code>

<h2>Isolating GRPC-specific details from business logic</h2>

The other task that is performed by the constructor above is storing a reference to a <code>user_management_service</code>, which is the implementation of the actual service business logic. That’s right, I’ve separated out GRPC-related code from the business logic.

The reason for this separation is that if we ever decide to expose service interfaces via REST or some other approach, we can reuse the business logic. In fact, I’ve tried to keep service implementations such as the <code>UserManagementService</code> class free from references to GRPC types, using types that are more idiomatic to Python where available.

A prime example of this would be converting the UUID type defined in the <code>common</code> package to the more standard Python <code>uuid.UUID</code>. The resulting type conversions turned out to be one of the most difficult portions of the GRPC-related code for me to implement. Which leads me to…

<h2>The hardest part of GRPC in Python</h2>

At the risk of going into too much detail in this post that is already on the long side, I wanted to highlight a special case that was very non-intuitive for me.

If you have operations in your services that can return a list of objects, you’ll want to educate yourself on the intricacies of generating the response object by reading this <a href="https://developers.google.com/protocol-buffers/docs/reference/python-generated#repeated-fields">portion</a> of the protobuf reference. Basically, you will need to use the <code>extend()</code> operation to populate any list values in your response objects.

Here’s an example from <code>user_management_service_grpc.py</code>:

<code>def UserModelList_to_GetUserProfileResponse(users): 
&nbsp; &nbsp;response = GetUserProfileResponse() 
​​​​​​​&nbsp; &nbsp;if isinstance(users, (list,)): 
​​​​​​​&nbsp; &nbsp;response.profiles.extend(map(UserModel_to_UserProfile, users)) elif users is not None: # single result ​​​​​​​&nbsp; &nbsp;response.profiles.extend([UserModel_to_UserProfile(users)]) 
​​​​​​​&nbsp; &nbsp;return response </code>

<h2>Wrapping up</h2>

To summarize, the setup of the User Management Service is as follows:

<ul>
	<li><code>killrvideo/user_management/user_management_service_pb2_grpc.py</code> — contains the generated GRPC stubs.</li>
	<li><code>killrvideo/user_management/user_management_service_grpc.py</code> — contains the subclass of the generated server stub which overrides the operation definitions, converts GRPC types to more natural Python types, and calls the actual business logic</li>
	<li><code>killrvideo/user_management/user_management_service.py </code>— contains the actual business logic</li>
</ul>

<h2>Coming up next</h2>

That’s it for this time. In the next post, we’ll examine some of our options for service discovery and how we’ve implemented this capability in killrvideo-python using <a href="https://coreos.com/etcd/">etcd</a>, read Part 3 of the KillrVideo Python series,&nbsp;Advertising Python Services via&nbsp;etcd,&nbsp;<a href="https://www.datastax.com/blog/2019/03/killrvideo-python-pt-3-advertising-python-services-etcd">here</a>.

This article is cross-posted from&nbsp;<a href="https://medium.com/@jscarp/python-app-dev-with-protobuf-and-grpc-e5bff779783d">Jeff's personal blog on Medium</a>.

KillrVideo Python Pt. 2 — App Dev with ProtoBuf and GRPC

Jeffrey CarpenterSoftware Engineer - Stargate

Discover more

Share

Share

Where to start?

Why GRPC?

Defining the GRPC APIs

Generating GRPC stubs

Implementing the services

The servicer

A subclass for GRPC server implementation

Registering services with the GRPC server

Isolating GRPC-specific details from business logic

The hardest part of GRPC in Python

Wrapping up

Coming up next

More Technology

How Winweb Built its AI Assistant with DataStax Astra DB and LangChain

Vercel + Astra DB: Get Data into Your GenAI Apps Fast

Simplifying Agent Development with Astra DB Connector for Vertex AI Search

Making Astra DB easier for MongoDB developers

One-stop Data API for Production GenAI