Handling backend restarts in Cloudflare Realtime SFU
The key change is simple: the adapter retries the same WebSocket endpoint for up to 5 seconds after a brief disconnect or restart. No API change is needed, so the caller side does not need to rebuild the session just because the backend blinked. If the endpoint comes back inside that window, media delivery resumes.
That is a useful boundary for a live media pipeline. It turns a short backend restart into a temporary interruption rather than a hard break in the stream. It also means a restart is still visible in behaviour, just not always visible to the client as a new session.
Why the adapter can survive a short backend restart without a new session
The adapter keeps the stream identity stable while it waits for the WebSocket endpoint to return. For a WebRTC SFU, that is the part that matters most. The media path stays tied to the same egress endpoint, so a short-lived restart in Workers, Containers, or whatever sits behind that endpoint does not automatically force the SFU to start from scratch.
That fits the way live media systems usually fail in practice. The backend goes away, comes back, and the transport layer needs to decide whether it treats that as a temporary fault or a terminal one. Here, the adapter picks temporary, but only for a short window.
Where the 5-second retry limit ends and a close still happens
The retry window is capped at 5 seconds. If the WebSocket endpoint is still unavailable after that, the adapter closes and must be recreated. There is no pretending a dead backend is merely “a little late”.
That limit gives a clean operational boundary. A restart that finishes quickly can be absorbed. A longer outage is treated as a failure, and the stream has to be rebuilt. That is a sane line for live media, because waiting forever for a backend that has gone missing is just a nice way to lose control of the session.
How audio and video recover differently after a WebSocket endpoint drops
Audio and video do not recover in the same way, because they are not equally forgiving. The adapter sends PCM audio frames and JPEG video frames, and the recovery logic reflects that. Audio can use a short bounded backlog during reconnect. Video resumes from the latest available frame rather than replaying stale ones.
That gives the pipeline a live-first bias. It favours current media over perfect continuity, which is usually the right trade in a stream that has to stay current.
Short audio backlog versus stale video frames
Audio can tolerate a little delay if the interruption is brief, so the adapter keeps a bounded backlog while it waits for the endpoint to return. If the outage runs too long, older audio can drop out of that backlog. That is preferable to feeding the listener a growing queue of out-of-date sound.
Video behaves differently. Once the endpoint is back, the adapter resumes from the latest JPEG frame available. It does not try to replay every stale frame that piled up during the interruption. That avoids the unpleasant effect where the screen catches up with yesterday before it reaches now.
What best-effort recovery means for gapless playback and packet order
Best-effort recovery is not a promise of gapless playback. It is not a promise of exactly-once delivery either. The adapter is built to recover quickly from short backend restarts, not to preserve every packet in perfect order through every interruption.
That is the part worth designing around. If the application needs strict continuity, this recovery model will not magic that into existence. It will resume delivery when it can, drop what no longer fits, and carry on with the newest media it has. That is acceptable for live playback, but it is not archival transport with a tidy conscience.
Designing the backend so reconnects stay boring
The backend has to be ready to accept the same stream again after a restart. If the endpoint comes back confused, changes identity, or needs a manual nudge to resume, the 5-second retry window loses most of its value. The adapter can only reconnect to something that is actually ready to take the stream.
The other half is testing the failure path. A system that looks fine when left alone can still fall apart the moment the backend restarts under load. That is the path that matters here.
Keep the WebSocket endpoint ready to accept the same stream again
The endpoint should come back in a state where the same stream can continue without a new setup dance. If the backend restart resets connection state in a way that breaks acceptance of the resumed egress stream, the reconnect window just becomes a countdown to closure.
That is a simple operational rule, but it gets missed often. Treat the restart path as part of the normal contract for the WebSocket endpoint, not as an edge case tucked behind a hopeful comment in the code.
Test the restart path, not just steady-state delivery
A media pipeline that only works while nothing changes is a polite lie. Restart the backend deliberately and watch what happens to the adapter, the audio backlog, and the video frame flow. Check whether the stream resumes inside the 5-second window and whether the backend accepts the returning connection without manual cleanup.
Also check the failure case. If the backend stays down, the adapter should close cleanly instead of hanging around in a half-dead state. That behaviour is easier to reason about than a stream that neither ends nor continues, which is a lovely way to waste an afternoon.
