fix: don't drop reconnect requests or lose their escalation

[xianshijing-lk]

Fixes CLT-3324. Stacked on #1197 (base is that branch, not main). Independent of #1198 — they touch different code and can merge in either order.

Problem

Three ways a reconnect request could be lost or altered in Engine:

1. Reason override — handleReconnect() clears the pending timer and reschedules with its own reason, so a later caller (the socket close that follows a server Leave) overrides an earlier one, and the escalation implied by the first reason is silently dropped.
2. Dropped request — attemptReconnect() early-returns on _attemptingReconnect, so a full-reconnect request arriving mid-attempt is never acted on.
3. Stale flag — a successful attempt calls _clearPendingReconnect(), cancelling the queued escalation and leaving fullReconnectOnNext stuck true, which also suppresses the next legitimate RoomDisconnectedEvent.

This is the mechanism behind #1197: pre-fix, whether a migration resumed or full reconnected depended on whether the socket-close handler beat the leave-driven Timer(0). In production the close arrives a round-trip later and loses, so the bug reproduced.

Fix

(1) The reason → escalation mapping moves from attemptReconnect to handleReconnect, where the request originates, so it is captured as state instead of being re-derived later from a reason that may have been replaced. The resumeConnection == DISABLED check stays in attemptReconnect — that's config, not a request.

(2)/(3) fullReconnectOnNext is consumed at the start of an attempt into a local. From there a true value unambiguously means a new request arrived while the attempt was running, which the finally block dispatches. This is client-sdk-js's pattern; rust-sdks does the equivalent with a sticky full_reconnect |=.

API note. Consuming the flag up front means it no longer describes the running attempt, which Room relied on to skip fast-connect republishing during a full reconnect's re-join (and to suppress the mid-reconnect disconnect event). Added Engine.isFullReconnectInProgress for that question and pointed Room at it. fullReconnectOnNext keeps its meaning as the pending request, so sendSimulateScenario(fullReconnect: true) and the connection check are unaffected.

Also aligns the failure path with js/rust: a failed full reconnect stays a full reconnect.

Tests

test/core/reconnect_request_dispatch_test.dart. The first test ports rust-sdks' test_resume_escalation_sticks_across_cycles (livekit/tests/peer_connection_signaling_test.rs), which needs a live SFU, two participants and a published sine track and observes the escalation via LocalTrackRepublished. The mock transport lets us inject the concurrent request directly and observe it as RoomReconnectingEvent, which only the full path emits.

• full-reconnect request injected mid-resume → cycle 1 still resumes, cycle 2 re-joins
• peerConnectionFailed followed by a signal request → still re-joins, does not resume
• successful resume → neither flag left set

Verified both behavioral tests fail against the pre-fix engine (test 1: cycle 2 never happens; test 2: reconnect=1, i.e. it resumed). Full suite (412 tests), flutter analyze, format and import_sorter all clean.

🤖 Generated with Claude Code

[devin-ai-integration]

Note

This report is out of date. Scroll down for Devin Review's latest report on this PR.

Devin Review found 1 potential issue.

[devin-ai-integration]

🟡 Mid-restart escalation is still dropped

During another full reconnect, fullReconnectOnNext can become false before this dispatch check. restartConnection clears it after joining, so the requested follow-up never runs.

Learn more

A reconnect request received during an attempt sets fullReconnectOnNext and schedules a timer. That timer can return at the _attemptingReconnect guard, leaving the flag as the only record of the request. A full reconnect then reaches restartConnection, which clears that shared flag before attemptReconnect checks it in finally. The follow-up request is therefore indistinguishable from no request and is dropped.

Example: A full reconnect is joining a replacement node when that node sends Leave{RECONNECT}. The handler sets fullReconnectOnNext = true, but the current join later clears it. The SDK reports the current attempt as successful and never performs the newly requested reconnect.

Recommended fix: Stop clearing pending reconnect state inside restartConnection. Let attemptReconnect consume only the request that selected the current attempt, while preserving requests recorded after that consumption point.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Devin Review found 1 new potential issue.

[devin-ai-integration]

🔴 Resume reconnect requests still disappear

When a resume request arrives during a successful attempt, fullReconnectOnNext remains false and blocks redispatch. _clearPendingReconnect cancels that request's timer, so the new disconnection gets no reconnect attempt.

Learn more

A reconnect request can arrive after the running attempt has passed the operation that prompted it but before that attempt finishes. handleReconnect schedules the new request regardless of its mode. The successful attempt then calls _clearPendingReconnect, cancelling that timer. This condition only preserves requests represented by fullReconnectOnNext, so resume requests still disappear.

Example: A resume reconnects signaling and receives SignalReconnectedEvent. Before its peer-connection work finishes, signaling disconnects again and schedules a resume. The first attempt succeeds, cancels the second timer, and emits success although signaling is now disconnected.

Recommended fix: Track whether any reconnect request arrived during the running attempt separately from its full-reconnect escalation. On success, dispatch the pending request with its captured reason and reconnectReason; preserve full escalation independently.

---

Was this helpful? React with 👍 or 👎 to provide feedback.