Add serve_grpc API

[jprochazk]

• Closes Provide API to spawn a gRPC server #9404

This PR adds the serve_grpc API to all our SDKs, and the --serve-grpc option to the CLI. It can be used to spawn a gRPC server without requiring users to also spawn a Viewer.

All of this is gated behind the server feature in both the CLI and our SDKs.

Examples

Connect a native Viewer to a gRPC server hosted by the SDK

Host a gRPC server, log some data to it, and then wait for incoming connections:

Python

import time
import numpy as np
import rerun as rr

rr.init("rerun_example_serve_grpc")
rr.serve_grpc()

SIZE = 10
pos_grid = np.meshgrid(*[np.linspace(-10, 10, SIZE)] * 3)
positions = np.vstack([d.reshape(-1) for d in pos_grid]).T
col_grid = np.meshgrid(*[np.linspace(0, 255, SIZE)] * 3)
colors = np.vstack([c.reshape(-1) for c in col_grid]).astype(np.uint8).T
rr.log("my_points", rr.Points3D(positions, colors=colors, radii=0.5))

# We have to explicitly wait here, otherwise the server will shutdown immediately.
while True:
  try:
    time.sleep(1)
  except KeyboardInterrupt:
    break

C++

#include <rerun.hpp>
#include <rerun/demo_utils.hpp>
#include <thread>
#include <chrono>

using rerun::demo::grid3d;

int main() {
    // Create a new `RecordingStream` which sends data over gRPC to the viewer process.
    const auto rec = rerun::RecordingStream("rerun_example_serve_grpc_cpp");
    // Try to spawn a new viewer instance.
    rec.serve_grpc().exit_on_failure();

    // Create some data using the `grid` utility function.
    std::vector<rerun::Position3D> points = grid3d<rerun::Position3D, float>(-10.f, 10.f, 10);
    std::vector<rerun::Color> colors = grid3d<rerun::Color, uint8_t>(0, 255, 10);

    // Log the "my_points" entity with our data, using the `Points3D` archetype.
    rec.log("my_points", rerun::Points3D(points).with_colors(colors).with_radii({0.5f}));

    // We have to explicitly wait here, otherwise the server will shutdown immediately.
    while (true) {
        std::this_thread::sleep_for(std::chrono::milliseconds(1000));
    }
}

Rust

use rerun::{demo_util::grid, external::glam};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let rec = rerun::RecordingStreamBuilder::new("rerun_example_serve_grpc_rs")
        .serve_grpc()?;

    let points = grid(glam::Vec3::splat(-10.0), glam::Vec3::splat(10.0), 10);
    let colors = grid(glam::Vec3::ZERO, glam::Vec3::splat(255.0), 10)
        .map(|v| rerun::Color::from_rgb(v.x as u8, v.y as u8, v.z as u8));

    rec.log(
        "my_points",
        &rerun::Points3D::new(points)
            .with_colors(colors)
            .with_radii([0.5]),
    )?;

    // We have to explicitly wait here, otherwise the server will shutdown immediately.
    loop {
        std::thread::sleep(std::time::Duration::from_secs(1));
    }
}

Then connect to the server:

rerun --connect

Connect a native Viewer to a gRPC server hosted by the CLI, with data supplied by the Python SDK

First, start the gRPC server:

rerun --serve-grpc

Then, log some data to it:

import numpy as np
import rerun as rr

rr.init("rerun_example_serve_grpc")
rr.connect_grpc()

SIZE = 10
pos_grid = np.meshgrid(*[np.linspace(-10, 10, SIZE)] * 3)
positions = np.vstack([d.reshape(-1) for d in pos_grid]).T
col_grid = np.meshgrid(*[np.linspace(0, 255, SIZE)] * 3)
colors = np.vstack([c.reshape(-1) for c in col_grid]).astype(np.uint8).T
rr.log("my_points", rr.Points3D(positions, colors=colors, radii=0.5))

Finally, connect to the server from a native Viewer:

rerun --connect

[github-actions]

Web viewer built successfully. If applicable, you should also test it:

• I have tested the web viewer

Result	Commit	Link	Manifest
✅	a293330	https://rerun.io/viewer/pr/9447	+nightly +main

^{Note: This comment is updated whenever you push a commit.}

[github-actions]

Latest documentation preview deployed successfully.

Result	Commit	Link
✅	a293330	https://landing-phta6aga7-rerun.vercel.app/docs

^{Note: This comment is updated whenever you push a commit.}

[emilk]

> rerun --serve-grpc
[… INFO  re_grpc_server] Listening for gRPC connections on 0.0.0.0:9876

> rerun --connect 0.0.0.0:9876
Error: invalid or missing scheme (expected `rerun(+http|+https)://`)

Let's improve the first message to

Listening for gRPC connections on 0.0.0.0:9876. You can connect to this server by running rerun --connect rerun+http://0.0.0.0:9876/proxy

The second error message could also be improved with:

…expected one of: rerun:// rerun+http:// rerun+https://

---

> rerun --connect rerun://0.0.0.0:9876/proxy
[… WARN  re_viewer::app] Data source rerun://0.0.0.0:9876/proxy has left unexpectedly: transport error

We should be able to improve this error message too, and hint about what went wrong.

What more common mistakes could the user do, and how can we help them in those situations?

[emilk]

Will this work even if the user already has #[tokio::main] on their fn main?

[jprochazk]

Yes, we're spawning a new thread and using a single-threaded runtime, so anything goes.

[jprochazk]

rerun --connect rerun://0.0.0.0:9876/proxy
[… WARN re_viewer::app] Data source rerun://0.0.0.0:9876/proxy has left unexpectedly: transport error

We should be able to improve this error message too, and hint about what went wrong.

We have no idea. tonic doesn't expose any concrete information about what went wrong, their error is a wrapper over Box<dyn std::error::Error>. They don't even expose the kind on tonic::transport::Error, so we can't even know for sure if what failed is related to forming a connection. It could literally be anything 🤷. All we can say for sure is that the connect call failed.

[emilk]

Nice

[emilk]

very nice