Message  Pack-RPC Client for Racket
1 Introduction
2 Usage
2.1 Client Creation
2.2 Synchronous Calls
2.3 Asynchronous Calls
2.4 Notifications
2.5 Client Shutdown
3 API
start-client
stop-client
rpc-call
rpc-notify
4 Warnings
5 Thanks/  Credits
7.0

MessagePack-RPC Client for Racket

Wil Thomason <[email protected]>

 (require msgpack-rpc) package: msgpack-rpc

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

      2.4 Notifications

      2.5 Client Shutdown

    3 API

    4 Warnings

    5 Thanks/Credits

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.