In this guide we’ll cover how Prim+RPC structures RPC messages and results. This may be useful to understand if you decide to write your own plugin or if you’d like to make a request to a Prim+RPC server in another language. The format is purposely kept simple so that requests are easy to make and results are easy to parse.
This is an advanced guide and is not required for most usages of Prim+RPC.
We will also touch lightly on how information may be sent over a protocol like HTTP but will focus primarily on the RPC part. Note that you do not need to read this guide to use Prim+RPC.
We’ve exposed an HTTP server running on
http://localhost:1234/prim and a WebSocket server at
ws://localhost:1234/prim. All requests sent to these addresses will be JSON.
We’ll use these addresses in any examples below when needed. All functions mentioned below should be added to the
Let’s say that we have set up a Prim+RPC server and gave it a module with a single function:
We can this easily call this from the Prim+RPC client with
client.add(1, 2). The resulting RPC message would become:
And the result would be given back as:
Note that the ID is random and optional but always used by the Prim+RPC client. If we only have one argument, we can omit the array and just pass the value itself. If the first function is an array, we simply wrap the array in an array with only one item: the array.
Let’s say we have a function that throws an error:
If we call
client.oops(), the resulting RPC call would become
And the result would be an error:
Since the function had thrown an error, the result property is missing and the error property is given instead. Note that we had thrown a string instead of a standard Error object. We could have done this instead:
The call remains the same but the resulting RPC result would become:
Prim+RPC can support callbacks given on a function. We’ll use a callback like so:
When we call
client.thinking("Ted", console.log), the Prim+RPC client will generate the following request:
Our callback was turned into a placeholder and the client will await results with this ID. We will receive a result from the server but also several additional messages from our callback. Results are given in order, in each tab:
We can support files (single or multiple) as both an argument but also a result. Let’s set up an example:
We could use this function in the client like so:
This call will be converted into the following RPC structure:
Note that our files were transformed into placeholders. JSON itself cannot support file types but typically our
transport can. For example when used over an HTTP server, Prim+RPC will send this data as FormData alongside a form-item
rpc containing the RPC message above along with two other form-items named
_bin_2 with the files
The result would become:
Since JSON cannot support files, we’ll receive a list of placeholder names alongside files given in our transport. When
the transport is HTTP, this will typically be FormData. Like the request object, we will receive an
rpc form-item with
the result above and two additional form-items with random identifiers that correspond to the file contents given in our
Finally, we can batch calls into one single request and receive one single response with all of our results. Typically this is only done over the method handler since the callback handler maintains an active connection and doesn’t necessarily benefit from batching.
By default the Prim+RPC client does not batch requests but we can set the Client Batch Time to a value greater than 0 to enable it.
Let’s say we have several functions and we can call them like so:
Our RPC would be batched like so:
Identifiers are highly suggested when batching to link back a function call to its result. The RPC result would become:
And when using the Prim+RPC client, our functions will receive their results as expected.Report an Issue