[go_router] Make ImperativeRouteMatch.complete idempotent

[ZephyrVentum]

Description

Adds an isCompleted guard inside ImperativeRouteMatch.complete so calling it a second time after the future has already resolved is silently ignored instead of throwing Bad state: Future already completed.

Root cause

GoRouteData ships a default FutureOr<bool> onExit(...) => true, and go_router_builder wires it into every generated $route factory. That makes routeBase.onExit != null for every route declared via @TypedGoRoute / GoRouteData, which forces every pop through the scheduleMicrotask path in GoRouterDelegate._handlePopPageWithRouteMatch:

scheduleMicrotask(() async {
  final bool onExitResult = await routeBase.onExit!(...);
  if (onExitResult) {
    _completeRouteMatch(result, match);
  }
});
return false;

Because the callback returns false, the Navigator does not mark the popped page as resolved synchronously — the page is only actually removed when the microtask eventually runs _completeRouteMatch → currentConfiguration.remove(match) → notifyListeners → Navigator rebuild without the page.

If the framework reaches _handlePopPageWithRouteMatch a second time for the same ImperativeRouteMatch before either microtask runs, both microtasks call _completeRouteMatch. The first one completes the Completer and removes the match; the second one calls completer.complete(value) against an already-completed Completer and throws.

Triggers observed in the wild include:

• iOS interactive back-edge swipe gesture firing Navigator.onPopPage more than once during the commit/animation window for Page-based routes.
• Chained context.pop(result) calls bubbling a value through nested modals.
• Async dialog dismiss racing the route under the dialog popping itself.

Behavior change

User-visible behavior is unchanged either way — currentConfiguration is already updated and notifyListeners rebuilds the Navigator without the popped page before the second microtask fires. The error only manifests as a noisy throw in apps' global error handlers (PlatformDispatcher.onError / FlutterError.onError), typically forwarded to crash-reporting as fatal.

With this patch, the second complete call is a no-op, the original future value is preserved, and no exception is thrown.

Tests

packages/go_router/test/match_test.dart gains one regression test under the existing group('ImperativeRouteMatch'):

test('complete is idempotent — second call is a no-op', () async {
  final completer = Completer<Object?>();
  final match = ImperativeRouteMatch(
    pageKey: const ValueKey<String>('idempotent'),
    matches: matchList1,
    completer: completer,
  );

  match.complete('first');
  // Must not throw.
  match.complete('second');

  expect(await completer.future, 'first');
});

Verified locally:

• dart analyze packages/go_router/ — clean.
• flutter test packages/go_router/ — 430 passed, 2 skipped (no regressions; new test passes).

Related Issues

• Fixes [go_router] ImperativeRouteMatch.complete() lacks isCompleted guard — races during iOS interactive pop + chained pops flutter#187326 (this PR's issue; full diagnosis + repro recipe).
• Also addresses the same root cause behind:
  • [go_router]: Bad state: Future already completed on context.pop() flutter#160696 (open) — chained context.pop() during loading-dialog dismissal.
  • [go_router] Chained pop operations in ShellRoute nested route-stack fail with Future exception flutter#176493 (closed) — chained pop in ShellRoute nested route-stack.
  • [go_router] "Bad state: Future already completed" when handling async login with modal navigation flutter#163813 (closed) — async login with modal navigation.
  • [go_router]: Bad state: Future already completed on go or goNamed after pop #123369 flutter#146938 (closed) — go / goNamed after pop.
  • [go_router]: Bad state: Future already completed on context.pop() flutter#123369 (closed, oldest) — original context.pop() complaint.

Pre-Review Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide and the packages style guide, including Features we expect every widget to implement.
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences].
• I linked to at least one issue that this PR fixes in the description above.
• I updated pubspec.yaml with an appropriate new version according to the pub versioning philosophy, or this PR is exempt from version changes.
• I updated CHANGELOG.md to add a description of the change, following repository CHANGELOG style, and updated or removed any TODOs.
• I updated/added relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or this PR is test-exempt.
• All existing and new tests are passing.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Code Review

This pull request updates the go_router package to version 17.2.4. It modifies the complete method in ImperativeRouteMatch to be idempotent by checking if the completer is already completed before calling complete again, preventing Bad state: Future already completed errors. A regression test has been added to verify this behavior, and the CHANGELOG has been updated. I have no feedback to provide.