[xianshijing-lk]

Port of livekit/client-sdk-js#2124.

The bug

Engine.reconnect computed its delay as:

var delay = defaultRetryDelaysInMs[_reconnectAttempts];
// Add random jitter to prevent thundering herd on reconnect
if (_reconnectAttempts > 1) {
  delay += math.Random().nextInt(1000);
}

Two problems, the same pair the JS SDK had before #2124:

1. The first two attempts get no jitter at all. defaultRetryDelaysInMs[0] is 0, so every client disconnected by the same event reconnects at the same instant, then again in lockstep 300ms later. The herd only begins to spread on the third attempt — by which point the server has already taken two synchronised waves.
2. The jitter that is applied is additive, not proportional. A flat 0–1000ms window swamps a 300ms delay (up to 4.3x) and barely perturbs a 7000ms one (14%).

Repro

Added test/core/reconnect_delay_test.dart. Against the current logic (first commit extracts the delay into reconnectDelayInMs with behaviour unchanged, so the test exercises the real code):

reconnect delay spreads out clients that disconnect at the same moment FAILED
  Expected: a value greater than <1>  Actual: <1>
reconnect delay later retries also vary between callers FAILED
  Expected: a value greater than <1>  Actual: <1>
reconnect delay scales jitter with the base delay FAILED
  Expected: a value less than or equal to <1800>  Actual: <1831>
  retry 2 exceeded 1.5x of 1200

100 callers asking for their first — and second — retry delay all got the identical value.

The fix

Scale each delay by a random factor in [0.5, 1.5). The first retry has a base delay of 0 with nothing to scale, so it draws from a fixed 0–500ms window instead; a zero at any later index is an explicit request to retry immediately and still passes through as zero.

Verification

flutter test — 471/471 pass (the three assertions above fail before the change). flutter analyze lib/src/core/engine.dart clean.

Note

reconnectDelayInMs is marked @internal; defaultRetryDelaysInMs was already public and is unchanged.

🤖 Generated with Claude Code

[xianshijing-lk]

Agreed — 500ms is longer than the 300ms that immediately follows it in this schedule, so it was slowing down the common case (a brief blip) without buying anything. The window only needs to be wide enough to pull a herd of clients apart, not to back off.

Dropped it to 150ms in 0e1a0f5. The first retry still fires fast, and 150ms of spread is plenty to decorrelate clients hitting the SFU at once.

This is now a deliberate divergence from the JS SDK, which uses 500ms — worth noting in case you'd rather keep strict parity across SDKs. The constant is maxFirstRetryJitterInMs, and the test asserts against it rather than a literal, so changing it is a one-line move either way.