First steps with Kotlin RPC

Local vs. remote procedure calls

Anyone with programming experience will be familiar with the concept of a procedure call. This is a fundamental concept in any programming language. Technically, these are local procedure calls, since they always take place within the same program.

A remote procedure call is when the function call and parameters are in some way transferred over a network, so that the implementation can occur within a separate VM/executable. The return value travels the opposite path back to the machine where the invocation was made.

It is easiest to think of the machine where the invocation occurred as the client and the machine where the implementation resides as the server. This does not necessarily have to be the case, however. RPC calls could occur in both directions, as part of a peer architecture. But to keep things simple, let’s assume a client/server deployment.

RPC framework fundamentals

Certain fundamentals must be provided by any RPC framework. They are inevitable when implementing remote procedure calls within a conventional IT infrastructure. The terminology can vary, and responsibilities can be divided in different ways, but every RPC framework must provide:

1. A way to declare the procedures that will be invoked remotely. In object-oriented programming, an interface is the logical choice. This could be the interface construct provided by the current language or some kind of language-neutral standard, such as the Web IDL used by the W3C

2. A means to specify the types used for parameters and return values. Once again, you could use a language-neutral standard. However, it may be simpler to annotate standard data type declarations in the current language.

3. Helper classes, known as client stubs, that will be used to convert the procedure invocation into a format that can be sent over the network and to unpack the resulting return value. These stubs can be created either during the compiling process or dynamically at runtime.

4. An underlying RPC Runtime that manages the helper classes and supervises the lifecycle of a remote procedure call. On the server side, this runtime will need to be embedded in some kind of server, so that it is available to process requests on an ongoing basis.

5. Protocols need to be chosen (or defined) to represent the procedure being called, serialize the data being sent, and transform the information over the network. In the past, some technologies have defined new protocols from scratch (IIOP in CORBA), while others have focused on reuse (HTTP POST in SOAP).

Marshaling vs. serialization

In RPC frameworks, we speak of marshaling and unmarshaling. This is the process of packing and unpacking information to be sent over the network. It can be thought of as a superset of serialization. In marshaling, we are serializing objects, but we also need to package information about the procedure being called and the context in which that call was made.

Create the project

First, you will create a project that will include both the client and server implementations.

In more complex applications, it's best practice to use separate modules for the client and server. However, for simplicity in this tutorial, we will use a single module for both.

Normally, you would immediately configure the project build file. However, that’s an implementation detail that won't enhance your understanding of the technology, so you'll get back to that step at the end.

Add the shared types

The heart of any RPC project is the interface that defines the procedures to be called remotely, along with the types used in the definition of those procedures.

In a multi-module project, these types will need to be shared. However, in this example, this step won't be necessary.

Implement the client

You only need 25 lines to prepare for and then execute an RPC call. Obviously, there is a lot going on, so let’s break the code down into sections.

The kotlinx.rpc library uses the Ktor client to host its runtime on the client side. The runtime is not coupled to Ktor, and other choices are possible, but this promotes reuse and makes it easy to integrate kotlinx.rpc into existing KMP applications.

Both the Ktor client and Kotlin RPC are built around coroutines, so you use runBlocking to create the initial coroutine, and execute the rest of the client within it:

Next, you create an instance of the Ktor client in the standard way. kotlinx.rpc uses the WebSockets plugin under the hood to transfer information. You only need to ensure that it is loaded by using the installRPC() function:

Having created this Ktor client, you then create a KtorRPCClient object for invoking remote procedures. You will need to configure the location of the server and the mechanism being used to transfer information:

At this point, the standard setup has been completed, and you are ready to use the functionality specific to the problem domain. You can use the client to create a client proxy object that implements the methods of the PizzaShop interface:

You can then make the remote procedure call and use the result:

Note that a tremendous amount of work is being done for you at this point. The details of the call and all parameters must be converted into a message, sent over the network, and then the return value received and decoded. The fact that this happens transparently is the payoff for the initial setup.

Finally, we need to shut down the client as usual:

Implement the server

The implementation on the server side breaks down into two parts. Firstly, you need to create an implementation of our interface, and secondly, you need to host it within a server.

Add dependencies

You now have all the code necessary to run the application, but at the moment, it would not even compile, never mind execute. At present, there is no wizard to create a kotlinx.rpc project for us, so you need to configure the build file manually. Fortunately, this is not too complex.

Run the application

To run the demo, follow the steps below: