Skip to content

Commit 1448f08

Browse files
authored
[go_router] Add BlockedInitialNavigationException for blocked initial deep links (#12213)
When `onEnter` returns `Block.stop()` on the very first navigation attempt (e.g. a deep link on web, before any route has been committed), the parser's `onCanNotEnter` path has no prior configuration to restore and reports a generic `GoException`. Apps handling this in `onException` can't tell "initial deep link blocked" apart from other routing errors (unmatched routes, redirect loops) without string matching on the exception message. This adds `BlockedInitialNavigationException extends GoException`, raised specifically in that no-prior-route path. It only refines the exception type — no change to when or whether an exception is thrown, and existing `is GoException` checks keep working. Apps can now write `if (state.error is BlockedInitialNavigationException)` in `onException` and, for example, redirect to a loading screen with the deep link preserved instead of treating it as a 404. Test: widget test in `on_enter_test.dart` — initial navigation blocked by `Block.stop()` with an `onException` handler; asserts the captured `state.error` is a `BlockedInitialNavigationException` (and still a `GoException`). Fixes flutter/flutter#189581 ## Pre-Review Checklist [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
1 parent b0d355f commit 1448f08

4 files changed

Lines changed: 46 additions & 1 deletion

File tree

‎packages/go_router/lib/src/misc/errors.dart‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,14 @@ class GoException implements Exception {
2525
@override
2626
String toString() => 'GoException: $message';
2727
}
28+
29+
/// Raised when `Block` is returned from `onEnter` but there is no prior
30+
/// route configuration to restore (e.g., an initial deep link was blocked).
31+
///
32+
/// Apps can check for this specific type in `onException` to recover
33+
/// gracefully (e.g., redirect to a loading screen with the deep link
34+
/// preserved) instead of treating it as a generic routing error.
35+
class BlockedInitialNavigationException extends GoException {
36+
/// Creates an exception for a blocked initial navigation attempt.
37+
BlockedInitialNavigationException(super.message);
38+
}

‎packages/go_router/lib/src/parser.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ class GoRouteInformationParser extends RouteInformationParser<RouteMatchList> {
132132
// Surface an error so the app decides how to recover via onException.
133133
final RouteMatchList blocked = _OnEnterHandler._errorRouteMatchList(
134134
effectiveRoute.uri,
135-
GoException(
135+
BlockedInitialNavigationException(
136136
'Navigation to ${effectiveRoute.uri} was blocked by onEnter with no prior route to restore',
137137
),
138138
extra: infoState.extra,
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
changelog: |
2+
- Adds `BlockedInitialNavigationException` (a `GoException` subtype), raised when the initial navigation is blocked by `onEnter` with no prior route to restore, so apps can distinguish this case in `onException` without string matching.
3+
version: minor

‎packages/go_router/test/on_enter_test.dart‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -868,6 +868,37 @@ void main() {
868868
expect(find.text('Fallback Page'), findsOneWidget);
869869
});
870870

871+
testWidgets('Should raise BlockedInitialNavigationException when the initial navigation '
872+
'is blocked by onEnter with no prior route to restore', (WidgetTester tester) async {
873+
Object? capturedError;
874+
875+
router = GoRouter(
876+
initialLocation: '/protected',
877+
onEnter:
878+
(
879+
BuildContext context,
880+
GoRouterState current,
881+
GoRouterState next,
882+
GoRouter goRouter,
883+
) async {
884+
if (next.uri.path == '/protected') {
885+
return const Block.stop();
886+
}
887+
return const Allow();
888+
},
889+
onException: (BuildContext context, GoRouterState state, GoRouter goRouter) {
890+
capturedError = state.error;
891+
},
892+
routes: <GoRoute>[GoRoute(path: '/protected', builder: (_, _) => const Placeholder())],
893+
);
894+
895+
await tester.pumpWidget(MaterialApp.router(routerConfig: router));
896+
await tester.pumpAndSettle();
897+
898+
expect(capturedError, isA<BlockedInitialNavigationException>());
899+
expect(capturedError, isA<GoException>());
900+
});
901+
871902
testWidgets('onEnter has priority over deprecated redirect', (WidgetTester tester) async {
872903
var redirectCallCount = 0;
873904
var onEnterCallCount = 0;

0 commit comments

Comments
 (0)