Real-time chat with Fitz: typed WebSockets and AsyncAPI auto-generated

Add a live click dashboard to the URL shortener from Part 2 using @ws("/path"), WsConn<T>, and the AsyncAPI 3.0 schema Fitz generates automatically. Same auth, same types, same binary.

The promise

In Part 2 we built a URL shortener: HTTP endpoints, Postgres ORM, JWT auth, native binary. Real and shippable, but every interaction is a request-response. Refresh the stats page to see the new click. Like 1998 again.

Today we make it live. When somebody clicks a short URL:

1. The HTTP handler still redirects and increments the counter (same as before).
2. A WebSocket subscribed to /dashboard gets a typed message with the click event.
3. The dashboard updates without polling.

The full diff against Part 2's code: ~40 lines. No new library installs. No websockets package, no socketio server, no redis for pub/sub. Just @ws on a function.

The typed WebSocket model

type ClickEvent {
    code: Str,
    target_url: Str,
    timestamp: Str,
}

@authenticated
@ws("/dashboard")
async fn dashboard(conn: WsConn<ClickEvent>, user: User) {
    log.info("dashboard.connected", { user_email: user.email })
    loop {
        let msg = match conn.recv() {
            Ok(m) => m,
            Err(_) => break,   // client disconnected
        }
        // For now we just echo back. In a real dashboard we'd ignore
        // incoming and only push out — `broadcast` is below.
        conn.send(msg)
    }
}

Three things in one decorator:

• @ws("/dashboard") — register a WebSocket endpoint at that path.
• WsConn<ClickEvent> — the typed connection. Every frame in or out is marshalled as ClickEvent.
• @authenticated — auth runs before the WebSocket upgrade. Bad token → 401, no socket opened, no network resources wasted.

@ws understands the auth_provider from Part 2. The same JWT verification function gates the dashboard.

Auto-marshalling, both directions

The HTTP body deserialization from Part 1 — type-checked JSON, defaults applied, missing fields detected, extras rejected — also works for WebSocket frames.

When the dashboard sends a frame, Fitz serializes the ClickEvent to JSON and sends. When a frame comes in, Fitz deserializes the JSON into ClickEvent and validates. If a frame is malformed, the recv() returns Err.

You don't write a single json.dumps/json.loads call. The compiler did it.

In contrast: the typical Python WebSocket loop:

# typical FastAPI / websockets server
@app.websocket("/dashboard")
async def dashboard(websocket: WebSocket):
    await websocket.accept()
    while True:
        try:
            data = await websocket.receive_text()
            msg = ClickEvent.model_validate_json(data)  # pydantic
        except WebSocketDisconnect:
            break
        except ValidationError as e:
            await websocket.send_text(json.dumps({"error": str(e)}))
            continue
        await websocket.send_text(msg.model_dump_json())

In Fitz:

@ws("/dashboard")
async fn dashboard(conn: WsConn<ClickEvent>) {
    loop {
        let msg = match conn.recv() {
            Ok(m) => m,
            Err(_) => break,
        }
        conn.send(msg)
    }
}

The Python version has the same logic but you have to spell it. The Fitz version has the logic in the type.

Broadcasting clicks live

Now we wire the click event from the HTTP redirect to the dashboard. The trick: broadcast on a WsConn<T> sends to every connection on the same endpoint, not just the one that called it.

@get("/{code}")
async fn redirect(db: DbConn, code: Str) -> Result<HttpResponse> {
    let link: Link = match Link.where(fn(l) => l.code == code).first(db).await {
        Ok(l) => l,
        Err(_) => return Err("not found"),
    }
    // Same as Part 2: spawn a background increment.
    spawn(increment_clicks(db, link.id))
    // New: broadcast the click event to the dashboard.
    spawn(notify_dashboard(link.code, link.target_url))
    return Ok(redirect_to(link.target_url))
}

@background
async fn notify_dashboard(code: Str, target_url: Str) {
    let event = ClickEvent {
        code: code,
        target_url: target_url,
        timestamp: now_iso(),
    }
    // The runtime keeps the broadcaster for `/dashboard` reachable
    // from anywhere via the typed handle.
    ws.broadcast("/dashboard", event)
}

The redirect handler hasn't changed in shape — it still returns the redirect response. We added one spawn. The background fn notify_dashboard calls ws.broadcast which fans out to every connection currently subscribed to /dashboard.

The broadcast is fire-and-forget. If no dashboards are connected, the call is a no-op. If 50 dashboards are connected, all 50 get the event. The runtime handles the list of active connections.

Heartbeat, baked in

WebSocket connections silently die in production. Some proxy decides 60 seconds of idle is too long, drops the TCP connection, and your client thinks it's still connected. Every WebSocket library has to add heartbeats; in Fitz it's a flag on the server:

@server(43929, ws_heartbeat_secs=30)
fn main() => 0

Every 30 seconds, the runtime sends a Ping frame on every WebSocket connection. If the client doesn't respond with Pong, the runtime considers the connection dead and closes it cleanly. Most proxies, including Nginx and Cloudflare, accept this as "still alive" and don't drop it.

Set ws_heartbeat_secs=0 to disable (default is 30).

This is the kind of feature you'd never bother to add yourself in a small project, then spend a Sunday debugging when production breaks. It's defaulted on for the same reason tcp_keepalive is defaulted on.

AsyncAPI generated automatically

OpenAPI describes HTTP services. AsyncAPI is its event-driven sibling — same schema model, but for WebSockets, Kafka, MQTT, etc. Fitz generates AsyncAPI 3.0 automatically, the same way it generates OpenAPI for HTTP:

curl http://localhost:8080/asyncapi.json

{
  "asyncapi": "3.0.0",
  "info": { "title": "shortener", "version": "0.1.0" },
  "channels": {
    "/dashboard": {
      "messages": {
        "ClickEvent": {
          "payload": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "target_url": { "type": "string" },
              "timestamp": { "type": "string" }
            },
            "required": ["code", "target_url", "timestamp"]
          }
        }
      }
    }
  },
  "operations": {
    "/dashboard.receive": { ... },
    "/dashboard.send": { ... }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
    }
  }
}

This is the full event API of your service. I don't know another language that auto-generates AsyncAPI from typed source. The AsyncAPI ecosystem has client generators (TypeScript, Java, Python), which means: drop the schema into studio.asyncapi.com or asyncapi generate, get a typed client for your front-end.

If you mark a server with @server(docs=false), neither OpenAPI nor AsyncAPI is exposed. Defaults are on because the cost is small and the value is large.

A minimal browser client

A 30-line vanilla JS client to test the dashboard:

<!doctype html>
<input id="token" placeholder="paste JWT token">
<button id="connect">Connect</button>
<ul id="events"></ul>
<script>
document.getElementById("connect").onclick = () => {
    const token = document.getElementById("token").value
    const ws = new WebSocket("ws://localhost:8080/dashboard", [], {
        headers: { Authorization: `Bearer ${token}` }
    })
    // Note: browser WebSocket constructors don't accept custom headers
    // directly. In production, you'd put the token in a query param
    // (?token=...) and have the auth_provider read it from there.
    ws.onmessage = (e) => {
        const event = JSON.parse(e.data)
        const li = document.createElement("li")
        li.textContent = `${event.timestamp} • ${event.code} → ${event.target_url}`
        document.getElementById("events").prepend(li)
    }
    ws.onerror = (e) => console.error("ws error", e)
    ws.onclose = () => console.log("disconnected")
}
</script>

Put this in a file, open in the browser, paste a JWT, click the connect button. Then in another terminal:

# Get a token (from Part 2's POST /login)
TOKEN=$(curl -s localhost:8080/login -X POST -H 'content-type: application/json' \
    -d '{"email":"ada@example.com","password":"secret-ada-123"}' | jq -r .token)

# Create a short URL
curl -X POST localhost:8080/shorten -H "Authorization: Bearer $TOKEN" \
    -H 'content-type: application/json' \
    -d '{"target_url":"https://github.com/Thegreekman76/fitz"}'

# Click the short URL — the browser's `events` list updates instantly
curl -I localhost:8080/abc123

The dashboard <ul> populates with the click event the moment the redirect happens. The browser was holding open a WebSocket; the click event got broadcast; the JS callback rendered it. Live.

Limitations and trade-offs

Honestly:

• One type per endpoint. WsConn<ClickEvent> means every frame in and out is ClickEvent. If you need both directions to be different types (In = ChatMessage, Out = ServerEvent), the workaround is to make the type a sum (union-style) — declare a wider Event type with optional fields. The cleaner solution (WsConn<In, Out> two-type generic) is on the roadmap.
• No rooms / channels within an endpoint. broadcast goes to every connection on the endpoint. If you want "broadcast only to users subscribed to project 42", you maintain a Map<Int, Vec<WsConn>> yourself or split into multiple endpoints (one per project — works fine for low counts).
• No reconnect with state replay. If the dashboard disconnects, on reconnect it sees new events only — there's no "give me the last 30 seconds I missed". Building that needs an event log (a Postgres table polled, or Redis Streams). Outside the WebSocket layer.
• Binary frames are supported via WsConn<Bytes>, but I haven't talked about them here. Useful for file uploads or audio streaming; the AsyncAPI emits format: binary.

These are the honest gaps. The 90% of WebSocket use cases (real-time updates, chat, live dashboards, multi-user collaborative editing for a single document) are covered today.

How this composes with the rest of Fitz

You can mix WebSockets with everything else:

• Auth: @authenticated/@admin/@requires("role") work on @ws, evaluated before the upgrade.
• Middleware: middlewares run before the upgrade for things like rate limiting per IP.
• ORM: the WebSocket handler can take a DbConn and query the database.
• Async: recv/send/broadcast are awaitable; combine with HTTP calls or Postgres queries inside the loop.
• Cron / spawn: cron jobs can ws.broadcast("/topic", event) to push periodic updates.
• OpenTelemetry: the auth check before upgrade emits a trace span; subsequent broadcasts can be traced too.

Same language, same types, same binary. The WebSocket isn't a separate world.

What you'd need next for a real product

The dashboard above is enough to demo "real-time URL shortener clicks". For a production product you'd extend with:

• Per-user filtering: only push clicks for URLs the user created. Trivial — check user.email == link.user_email before broadcasting, or split into one endpoint per user with the email in the path.
• Aggregation: don't send every click; send a rate of clicks per code per second. Maintain state in the handler, send aggregated frames every 1 second.
• Frontend framework integration: TypeScript types from the AsyncAPI schema. Run asyncapi generate once.

None of these change the Fitz code structure. They're all "edit the broadcast call site".

Try it

# Linux / macOS / WSL
curl -sSf https://thegreekman76.github.io/fitz/install.sh | sh

# Windows (PowerShell)
irm https://thegreekman76.github.io/fitz/install.ps1 | iex

# Reopen the terminal, then:
git clone https://github.com/Thegreekman76/fitz.git
cd fitz/boilerplates/api-websocket

# Read the README, run with docker compose or `fitz dev`
docker compose up

For VSCode (recommended — WsConn<T> hover, autocomplete on conn.send/recv/broadcast): grab the fitz-lang-<platform>.vsix from the releases page and code --install-extension fitz-lang-<platform>.vsix --force. The Language Server is bundled.

The api-websocket boilerplate is a typed chat server. Pretty much the same shape as the dashboard above — loop { recv; broadcast } with auth.

For the full URL shortener + live dashboard, the api-orm-full boilerplate has the whole thing assembled (HTTP routes + ORM + WebSocket dashboard + cron job + JWT auth) in ~250 lines total.

Repo: github.com/Thegreekman76/fitz
api-websocket boilerplate: github.com/Thegreekman76/fitz/tree/main/boilerplates/api-websocket
api-orm-full boilerplate (the full thing): github.com/Thegreekman76/fitz/tree/main/boilerplates/api-orm-full
Docs and course: thegreekman76.github.io/fitz
Guide chapter on WebSockets: thegreekman76.github.io/fitz/guide/#29-websockets
Roadmap: docs/roadmap.md
CHANGELOG: CHANGELOG.md
Issues: github.com/Thegreekman76/fitz/issues

If you build something with this, write to me. I want to see it.

Until the next one.