Getting started with realtime

umbral-realtime is the "Supabase feeling" for umbral: subscribe to live data and presence from the browser, push from the server with one line, and stay safe by default. There is no socket bookkeeping, no polling, and no serializer code to write.

This page is the five-minute path: install the plugin, wire identity, add the client script, and send your first end-to-end event.

1. Install the plugin

Add umbral-realtime to your binary crate and register the plugin on the app builder. With nothing else configured you get both transports mounted (GET /realtime/sse, GET /realtime/ws) and the ambient Realtime handle for sending.

use umbral::prelude::*;
use umbral_realtime::RealtimePlugin;
 
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let app = App::builder()
        // ... your settings, database, models, routes ...
        .plugin(RealtimePlugin::new())
        .build()?;
 
    umbral_cli::dispatch(app).await
}

2. Wire identity (so the framework knows who's connecting)

By default every connection is anonymous - the identity resolver returns None. That's fine for a fully public feed, but if you want to gate rooms by user or use presence, the framework needs to know who's connecting. The resolved identity is user_id: Option<String> - the user's primary key rendered to its canonical string, so it works for any PK type (i64 → "42", uuid → "550e8400-…").

If you use umbral-auth, enable the auth feature and call with_auth_sessions(). It identifies the connecting user from the session cookie at the SSE/WS handshake:

RealtimePlugin::new()
    .with_auth_sessions()   // requires the `auth` cargo feature

For a custom scheme (JWT, API key), supply your own async resolver - see Gating access.

3. Add the client script

The plugin serves a tiny browser helper at GET /realtime/client.js. Add one script tag to your template; it exposes the umbral.realtime namespace.

<>
<script src="/realtime/client.js"></script>
</>

There is nothing to bundle or import - the script registers window.umbral.realtime with subscribe, model, and presence.

-  <script src="/realtime/client.js"></script>
+  <script src="/realtime/client.js"></script>
<script>
  const sub = umbral.realtime.subscribe("public:lobby", {
    ping: (data) => console.log("got ping", data),
  });
  // later: sub.unsubscribe();
</script>

use umbral_realtime::Realtime;
use serde_json::json;
 
Realtime::to_group("public:lobby")
    .send("ping", &json!({ "message": "hello room" }))
    .await;