
# Filters, guards and errors

Before a navigation opens its screen, filters may send it elsewhere: a `RouteFilter` returns `null` to go on, or a location to go to instead. With [spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/index.md), `@PreAuthorize` on a screen is such a guard: nobody logged in goes to the login, and back after it. Unknown addresses show the not-found screen, and a navigation that fails shows the error screen.

## Why

Who may open a screen is a rule of the app, not of each button that leads there. A filter decides once, for every way in: a tap, the address bar, a deep link, the back button. A guard written as `@PreAuthorize("hasRole('ADMIN')")` reads like a Spring method's.

## Filters

```dart
// Only administrators open /admin/**; everyone else goes to the catalog.
@Component()
final class AdminOnly implements RouteFilter {
  AdminOnly(this.session);

  final Session session;

  @override
  RouteLocation? filter(RouteRequest request) =>
      request.state.matches('/admin/**') && !session.isAdmin
          ? RouteLocation('/catalog')
          : null;
}
```

- `RouteFilter` beans run for every route, in `@Order`. Filters of a route (`.filter(...)` in Dart configuration, for the routes of a `nest`) run after them, in the order declared.
- A filter may be async (`FutureOr<RouteLocation?>`).
- `RouteRequest` has the `state` (the route with its location and values), `location` and `route` (`null` for an unknown address).
- A filter that throws shows the error screen.

## Guarded screens

With the security starter, `@PreAuthorize` on a screen takes the expressions of method security:

```dart
@ScreenRoute('/admin', title: 'Admin')
@PreAuthorize("hasRole('ADMIN')")
class AdminPage extends StatelessWidget { ... }
```

```yaml
spring:
  flutter:
    navigation:
      login: /login
```

- Nobody logged in goes to `spring.flutter.navigation.login`, and back to the screen after the login. Without the property, such a navigation shows the error screen.
- A logged-in user without the role gets the error screen.
- After a logout, the screen on top is opened again through the guards.
- In Dart configuration: `.filter(RouteSecurity.preAuthorize("hasRole('ADMIN')"))`.
- A guarded route without the security starter (no `RouteAuthorizationFilter` bean) stops the start, rather than open the route to everyone.
- A guard hides screens on the device; the server still checks every request.

## The not-found screen

```dart
@ScreenRoute.notFound()
class NotFoundPage extends StatelessWidget {
  const NotFoundPage({super.key});

  @override
  Widget build(BuildContext context) =>
      Center(child: Text('Nothing at ${context.route.uri}'));
}
```

## The error screen

A navigation that fails (a value that does not convert, such as `?page=abc` for an `int`; a filter that throws; a guard that refuses) shows the error screen: `.error(...)` in Dart configuration, else a plain one. Its `RouteState.error` says why.

## Refused addresses

An address with an encoded slash or backslash, a backslash, an encoded NUL, or a `.` / `..` segment (once decoded) opens nothing: the app stays on its screen, or opens its first screen when it was opened by such a link. Such an address could otherwise stay on one route while its `{*rest}` value named a file of another route's folder, past that route's guard. Plain dot segments in a typed address are resolved first, so they reach the screen they name, guard included.

## Links from outside

Every deep link goes through the routes, filters and guards included. `@RouteInfo(link: false)`, or a path under `spring.flutter.navigation.deep-links.exclude`, keeps a screen from opening by a link; the app's first screen opens instead (see [The web and deep links](web-and-deep-links.md)).

## In Spring (Java)

A `RouteFilter` is a `HandlerFilterFunction` of `RouterFunctions`. `@PreAuthorize` is method security's, evaluated by the security starter.

## See also

- [spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/index.md)
- [Screens and routes](screens.md)
- [Routes in Dart configuration](dart-configuration.md)
