Connection

The first subscribe() opens a WebSocket. The client keeps it healthy: heartbeats, automatic reconnecting, and rejoining your channels. You rarely need more than the status.

Status

pawabase.realtime.status;    // "idle" | "connecting" | "open" | "reconnecting" | "closed"

const stop = pawabase.realtime.onStatusChange((status) => {
  offlineBanner.hidden = status === "open";
});

room.subscribed                                  # True while joined
room.on("closed", lambda reason: show_offline())

Show a small “reconnecting” hint when the status isn’t open. Channels rejoin by themselves.

Open and close

await pawabase.realtime.connect();
pawabase.realtime.disconnect();       // close and stop reconnecting

await pb.realtime.connect()
await pb.realtime.close()

Disconnect when you discard a client (on sign-out) so timers stop. In Python, async with AsyncPawabase(...) does it for you.

Options (TypeScript)

const pawabase = createClient({
  url, apiKey,
  realtime: {
    heartbeatSeconds: 25,
    reconnect: { baseDelayMs: 500, maxDelayMs: 15_000, maxAttempts: 20 },
  },
});

Option	Default	Meaning
`heartbeatSeconds`	25	Ping interval. A connection silent for two intervals is replaced
`ackTimeoutMs`	10000	How long to wait for the server to accept a request
`connectTimeoutMs`	10000	How long to wait for the connection to open
`reconnect`	on	Backoff settings, or `false` to stay closed after a drop
`webSocket`	built in	A WebSocket class, for older Node versions: pass `ws`

One-way streams

If you only listen (a dashboard, a server process) use Server-Sent Events over plain HTTP: no socket to manage, works through strict proxies. Up to 20 channels per stream.

for await (const frame of pawabase.realtime.stream(["chat:lobby", "order:42"])) {
  if (frame.type === "message") show(frame.payload);
}

for frame in pb.realtime.sse(["chat:lobby", "order:42"]):
    if frame["type"] == "message":
        show(frame["payload"])

Frames are welcome, message and presence_diff. To send, use publish. Stop with an AbortSignal (TypeScript) or by breaking the loop.

Signing in and out

The connection follows the person. When the access token refreshes the socket stays alive; when they sign out, channels that needed a person close. After a new sign-in, subscribe again.

What can go wrong

Situation	What you see
A rule refuses you	`subscribe()` / `send()` throws `RealtimeError`
The connection drops	Status becomes `reconnecting`; channels emit `closed`, then rejoin
Wrong key or project	The connection closes and doesn’t retry
Server unreachable	Reconnect attempts back off until `maxAttempts`

Watch connections open and close in Studio: Services → Realtime → Connections and Overview.

Protocols

Other ways to connect.

Troubleshooting

Fix connection problems.

Getting started

Set up in Studio

Use it from your app

Build well

Status

Open and close

Options (TypeScript)

One-way streams

Signing in and out

What can go wrong

Protocols

Troubleshooting

​Status

​Open and close

​Options (TypeScript)

​One-way streams

​Signing in and out

​What can go wrong

Protocols

Troubleshooting

Status

Open and close

Options (TypeScript)

One-way streams

Signing in and out

What can go wrong