Skip to content

eliaperantoni/spaceman

Repository files navigation

Spaceman is a cross-platform gRPC client designed to be pleasant to use and pretty to look at. It is available both as a desktop GUI and as a CLI. Its main use-case is manual testing and debugging of gRPC server: simply load a Protobuf descriptor, choose your request, fill in the input message body and send away, to infinity and beyond!

Ok but what's gRPC

gRPC is a modern high-level communication protocol developed at Google. In my mind, gRPC falls more or less in the same basket as HTTP. Nowadays, the latter is not just limited to serving webpages and REST APIs anymore: many applications, that have nothing to do with the web, communicate using it. I like to think of gRPC as a better way to do that.

Some of the advantages are:

  • A dedicated, official, SDK is available for many programming languages. The SDK includes code generation utilities that make serving a gRPC service, or consuming one, a breeze as all the encoding, decoding, and data validation is done for you. For instance, calling a procedure on a remote server is as easy as calling a generated function and building a server usually boils down to implementing a method for each available endpoint.
  • Exchanged messages are strongly typed with the Protobuf3 schema language (some degree of free-typing is opt-in). This is great for avoiding the headaches of fields missing or having an unexpected type. In my experience, the schema file alone is already great documentation in and of itself when working in a small team. See playground.proto for an example.
  • When working with a compiled language, the code generated by the SDK provides useful static typing. If your application doesn't communicate correctly, it won't even compile.
  • Messages are binary encoded and, because there is no need for them to be self-describing, they are usually smaller than their JSON-encoded counterpart. Encoding and decoding the messages is performant and often takes less time than JSON.parse-ing the same message in JavaScript.
  • Apart from the usual "send a request, receive a response", gRPC also supports the client and/or the server asynchronously sending messages as long as they want to. When a procedure is streaming from both sides, you effectively have full-duplex communication just like WebSockets or socket.io.
  • It is interoperable with HTTP if you need it.

In Action

demo.mp4

Building

Requirements:

  • Rust (rustup is recommended)
  • The wasm32-unknown-unknown build target for Rust (if you have rustup, you can install it with rustup target add wasm32-unknown-unknown)
  • Tauri
  • Trunk
# To build the CLI
$ cargo build --release -p spaceman_cli

# To build the GUI
$ pushd spaceman_gui_back
$ cargo tauri build
$ popd

Protobuf

Spaceman loads compiled Protobuf descriptor files to know which services it can interact with, the methods that each provides, and the format of all exchanged messages so it can properly encode/decode them, as well as offer some basic editing capabilities.

Note that these files are not the same thing as the source .proto file, but they are what you obtain when compiling with protoc instead. Here's how you would compile multiple .proto files into a single descriptor file, recursively including all imports so that it's self-contained and can be loaded into Spaceman from any computer:

$ protoc --include_imports -o load_me.desc *.proto

Technology Stack

Spaceman is built in Rust using Tonic (part of the Tokio ecosystem) for making gRPC calls and heavily relies on Prost-Reflect to interpret Protobuf messages not known at compile time. That's the core of it, the CLI is just a facade built with Clap.

The GUI uses Tauri as a framework for making webview-based desktop apps and the actual frontend is made with Yew: a Rust reactive framework that compiles down to WebAssembly. The text editors are built with Monaco, the same technology that powers Visual Studio Code.

Miscellaneous

Q: Is the project actively maintained
A: Not really, I built this for my own usage (if even that) just because I felt like building something cool with Rust and I thought it came out nice enough to give it a logo and a detailed README.

Q: I'm on Linux and the app behaves weirdly at times
A: This is something that I experienced myself but I really can't do much about it. Tauri uses WebKit2GTK for rendering the webview on Linux and unfortunately, it doesn't play too nicely with WebAssembly. From my (limited) research, the issues that arise more frequently were solved in WebKit a long time ago but the fixes haven't made it into WebKit2GTK yet.