mrpc

README

Mrpc

Installation

Generate the binary from source.

$ ./test/build.sh

For the Mrpc command line to work, the Mrpc installation path has to be added to the PATH environment variable. This can be done by editing the $HOME/.profile file and appending the path as follows:

Access the .profile file using the following bash command.

$ vim ~/.profile

Add the following environment variable in the file.

export MRPCPATH=[Installation Path]
export PATH=$PATH:$MRPCPATH/bin

Defining an Mrpc Protocol File

Start by creating a new Mrpc protocol file first_project.mrpc for your project (Mrpc uses the extension ``.mrpc` for all Mrpc protocol files).

Writing the protocol file

# Package `cache` defines a cache server.
package cache

# Server `cache`.
server cache { }

Here, we have created a new Mrpc package called cache. An Mrpc package specifies the entire protocol, such as the server, its APIs and the input and output messages it will use for sending a request or receiving a response.

Under the package cache, define a server cache as well. Let us also add two new message types as well, which will be the data format we'll use to send a request or to receive a response.

# Request message type.
msg request {
    # The key of the cache item.
    str key;

    # The value of the cache item.
    str val;
}

# Response message type.
msg response {
    # The status of the response.
    int32 status;

    # The value of the cache item.
    str val;
}

For our input message, we define a new message request, for which we define two fields: key and val (both of type string). The name request here is just used for simplicity; in general, the name for a message could be anything. For retrieving an item from the cache, we will only set the key, whereas for inserting an item, we will set both the key and the value.

For our response, we define two fields: status and value. The status field represents any status code that the server may send as a response, whereas the val field represents the returned value of the cache item. Like request, the name response is just used for simplicity.

Now, we list down the APIs for the server. We define two APIs set and get as follows:

# Server `cache`.
server cache {
    # Get the value for the provided key.
    api get(request) -> (response);

    # Set the value for the provided key.
    api set(request) -> (response);
}

Both APIs take in the message request as input and return the message response.

Structure of an Mrpc file

Each Mrpc file defines a package which lists down a server. For each server, we define one or more APIs that the server uses. Furthermore, each Mrpc file defines one or more message types that are used by the APIs as inputs or outputs. The complete structure of the file for the above example is:

# Package `cache` defines a cache server.
package cache

# Server `cache`.
server cache {
    # Get the value for the provided key.
    api get(request) -> (response);

    # Set the value for the provided key.
    api set(request) -> (response);
}

# Request message type.
msg request {
    # The key of the cache item.
    str key;

    # The value of the cache item.
    str val;
}

# Response message type.
msg response {
    # The status of the response.
    int32 status;

    # The value of the cache item.
    str val;
}

Generating the Code.

Before we can generate the code for our Mrpc file, we need to specify the path at where the code will be generated, as well as the languages for which we need to generated code. To do this, we specify an option for the package cache as follows:

# Package `cache` defines a cache server.
@opt golang_package "mslm/cache"
package cache

The option @opt golang_package specifies that the language for which the package is required is Golang and the path is mslm/cache.

For our cache server, we also need to define the protocol used by the server. Mrpc currently supports two protocols HTTP and Mconn. Like specifying the path, we add in another option for our server as follows:

# Server `cache`
@opt protocol "http"
server cache {
    ...
}

The underlying protocol used by the server will be HTTP.

Now, we can build the file. Return back to the root directory mslm/ and run the following command:

$ mrpc build first_project.mrpc

If there are no errors in your code, the program will be compiled successfully and several files will be generated in the specified directory. For our example, three files are generated:

mslm/cache/cache_msg.go
mslm/cache/cache_server.go
mslm/cache/cache_client.go

Supported Languages

• Golang
• Typescript