MessagePack-RPC Client for Racket

8.16.0.1

MessagePack-RPC Client for Racket🔗ℹ

Wil Thomason <wbthomason@cs.cornell.edu>

This package implements a RPC client in accordance with the MessagePack-RPC spec. It supports calls (asynchronous and synchronous) and notifications, and can use TCP and UNIX domain sockets as transports.

The source is at: https://github.com/wbthomason/msgpack-rpc-racket

PRs and issues are welcome!

1 Introduction

2 Usage

2.1 Client Creation

2.2 Synchronous Calls

2.3 Asynchronous Calls

1 Introduction🔗ℹ

MessagePack-RPC is a simple, efficient RPC protocol using the MessagePack serialization library.

This package implements a client for the MessagePack-RPC protocol in Racket.

2 Usage🔗ℹ

The basic usage flow for the library is: Create a client connected to some MessagePack-RPC server. Perform a sequence of calls using the client. Shut down the client. Below are examples of these operations.

2.1 Client Creation🔗ℹ

Here we show how to connect using TCP to a server running at port 5781 on localhost.

(define client (start-client "127.0.0.1" 5781 "tcp"))

2.2 Synchronous Calls🔗ℹ

Next, we’ll make a synchronous call to a method named "plusone" with the argument 4, and check the result.

(match-let ([(list err result) (rpc-call client "plusone" 4)])
           (if (not (void? err))
               (printf "Got error: ~a\n" err)
               (printf "Got result: ~a\n" result)))

2.3 Asynchronous Calls🔗ℹ

Now we’ll make the same call, but asynchronously.

(define chan (rpc-call client "plusone" 4 #:sync? #f))
(match-let ([(list err result) (async-channel-get chan)])
                       (if (not (void? err))
                           (printf "Got error: ~a\n" err)
                           (printf "Got result: ~a\n" result)))

2.4 Notifications🔗ℹ

Next, we’ll send a notification to the method "sayhi" with an argument "Racket".

(rpc-notify client "sayhi" "Racket")

2.5 Client Shutdown🔗ℹ

And, finally, we’ll shut down the client we’ve been using.

(stop-client client)

3 API🔗ℹ

procedure
(start-client addr [port-num conn-type]) → (class?)
  addr : string?
  port-num : exact-positive-integer? = null
  conn-type : string? = "unix"

Constructs a client and opens a connection to the specified RPC server.

procedure
(stop-client client) → any
client : (is-a? rpc-client%)

Stops a client’s event loop and closes its connection.

procedure
(rpc-call client
method
#:sync? boolean?
args ...) → any
  client : (is-a? rpc-client%)
  method : string?
  boolean? : #t
  args : any

Make a call to the method specified by method on the RPC server client is connected to, with the arguments given in args. If #:sync is #t, block until the call returns, then return (list err result), reporting any errors in the call and the result, if any, of the call. If #:sync is #f, do not block, and immediately return the async-channel which will contain the call results in the same (list err result) format as before when the call returns.

procedure
(rpc-notify client method args ...) → any
  client : (is-a? rpc-client%)
  method : string?
  args : any

Send a notification to the method specified by method on the RPC server client is connected to, with the arguments given in args. A notification is essentially a call that expects no result in return.

4 Warnings🔗ℹ

This package has been tested manually and verified to work. I have not yet written unit tests, or any sort of formal tests, so caveat emptor. There are also quite likely code smells and non-idiomatic Racket usages; this is the first significant Racket I’ve written.

All that said, this works as expected in my uses of it, and I didn’t find an alternative when I searched.

5 Thanks/Credits🔗ℹ

This module uses the (excellent) msgpack library by HiPhish. After I wrote this module, I discovered HiPhish’s RPC implementation in his Racket Neovim client; however, this module is less specialized to use with Neovim, uses a different client model and API design, and is designed for general-purpose standalone msgpack-rpc use.