Web UI¶
The playground ships a small browser UI so you can watch both RPC shapes in action without writing a client.
Run it¶
# terminal 1 — the gRPC server (the real thing, on :50051)
uv run python -m server.server
# terminal 2 — the UI bridge
uv run python -m ui.web # http://localhost:8090
Open http://localhost:8090. The page opens a Subscribe stream on load —
then every event you send appears live in the feed.
What the page shows¶
- Status pill (top right) — polls
/api/health, which does a realchannel_ready_futurecheck against:50051. Red pill = start the gRPC server. - Send an event (left) — one click = one
SendEventunary RPC. The result line shows the returnedevent.idanddelivered_to— how many openSubscribestreams received it. - Live stream (right) — a WebSocket mirror of one
Subscribecall. Unsubscribe/re-subscribe to watchdelivered_togo to 0 and back: if the stream isn't open, the event is gone — there is nothing to retry.
Why a bridge?¶
Browsers can't speak gRPC's HTTP/2 framing natively (gRPC-Web exists but
needs a proxy like Envoy). So ui/web.py is a thin FastAPI app
that is itself an ordinary gRPC client:
| Browser side | Bridge | gRPC side |
|---|---|---|
POST /api/events |
→ SendEvent |
unary RPC |
WS /ws/subscribe |
→ Subscribe |
server-streaming RPC |
GET /api/health |
→ channel readiness | connectivity check |
flowchart LR
B[Browser UI] -- "HTTP POST" --> W[FastAPI bridge :8090]
W -- "SendEvent RPC" --> S[gRPC server :50051]
S -- "Subscribe stream" --> W
W -- "WebSocket" --> B
One event, end to end¶
What happens from page load to seeing an event appear:
sequenceDiagram
autonumber
participant B as Browser
participant W as ui/web.py<br/>bridge (gRPC client)
participant S as server/server.py<br/>EventBusServicer
B->>W: WS /ws/subscribe (page load)
W->>S: Subscribe() — gRPC stream opens
S-->>S: new queue.Queue added to subscribers
Note over B,W: WebSocket lifetime == gRPC call lifetime
B->>W: POST /api/events {type, data_json}
W->>S: SendEvent() — unary RPC
S-->>S: Event built, q.put() on every subscriber queue
S-->>W: SendEventResponse (event, delivered_to=1)
W-->>B: JSON {ok, event, delivered_to}
S-->>W: Event — pushed down Subscribe stream
W-->>B: event over WebSocket — appears in feed
B-xW: Unsubscribe / tab close — WS closes
W-xS: call.cancel() — stream ends, queue removed
Note over S: no subscribers → next event: delivered_to=0
Nothing is re-implemented — the bridge calls the same generated stubs
(events_pb2, events_pb2_grpc) the CLI demo uses. The event bus, the
queues, and the fan-out all still live in server/server.py.
Check yourself¶
Why does the browser need ui/web.py in between it and the gRPC server?
Clicking Unsubscribe in the UI does what on the gRPC side?
You send an event and see delivered_to: 0. What happened?
Files¶
| File | Role |
|---|---|
ui/web.py |
FastAPI bridge — REST + WebSocket → gRPC client calls |
ui/static/index.html |
single-page UI, no build step |