
# Server side

These are the interfaces a web server and the application meet on. The web starter's `dart:io` server and its `MockMvc` both implement them, so filters, controllers and WebSocket endpoints never see which server is behind them. You use them when you write a filter or a handler by hand, or a library that plugs into the server.

## Why

A filter written against `ServerHttpRequest` runs on the real server and in `MockMvc` tests alike. A deadline carried in the request's `Zone` limits every call the request makes, wherever it is in the code.

## Example

```dart
final pattern = PathPattern.parse('/books/{isbn}');
pattern.match('/books/978-0')?.variables; // {isbn: 978-0}
pattern.matches('/books/');               // false: a trailing slash matters, as in Spring 6

// A health check answered before any controller is looked at.
final class HealthMapping implements HandlerMapping {
  @override
  HttpHandler? getHandler(ServerHttpRequest request) => request.path == '/health'
      ? FunctionHttpHandler((request, response) => response.send(200, 'UP'))
      : null;
}

// At most 2 seconds for the whole checkout, whatever the calls inside do.
final order = await RequestDeadline.run(const Duration(seconds: 2), () => checkout(basket));
```

## The types

| Type | Spring | What |
|---|---|---|
| `ServerHttpRequest` | `ServerHttpRequest` | `method`, `uri`, `path`, `headers`, `queryParameters`, `cookies`, `remoteAddress`, `isSecure`, `attributes`, `principal`; `body` (a stream, read once) with `readBodyBytes`, `readBodyText`, `contentType`; `isWebSocketUpgrade`, `upgradeToWebSocket`. |
| `ServerHttpResponse` | `ServerHttpResponse` | `statusCode` and `headers` (until `isCommitted`), `addCookie(ResponseCookie(...))`, `add`, `write`, `flush`, `addStream`, `close`, `done` (closed, or the client went away); `send(status, text)`. |
| `ServerHttpRequestDecorator`, `ServerHttpResponseDecorator` | the same | Forward everything to a delegate. Extend one and override a single member, in a filter that changes the path or the principal. |
| `ResponseCookie` | `ResponseCookie` | A `Set-Cookie` value: `maxAge`, `domain`, `path`, `secure`, `httpOnly`, `sameSite`, `partitioned`. |
| `Principal` | `java.security.Principal` | Who sent the request (`name`); set by an authentication filter. |
| `HttpHandler`, `FunctionHttpHandler` | `HttpHandler` | Answers one request. The web starter's dispatcher is one. |
| `HandlerMapping` | `HandlerMapping` | Finds the handler for a request (`getHandler`, or `null`). The web starter asks every `HandlerMapping` bean, in `@Order`. |
| `RequestContextHolder` | `RequestContextHolder` | `currentRequest`: the request being handled, from anywhere in its handling. Each request runs in its own `Zone`. |
| `RequestDeadline` | none | A time limit for the total work of a request (below). |
| `PathPattern` | `PathPattern` | Path patterns (below). |
| `AllowedOrigins` | `CorsConfiguration`'s origin checks | The browser origins a server allows (below). |

## RequestDeadline

A time limit for the total work of a request, found through the `Zone`:

| Member | Meaning |
|---|---|
| `RequestDeadline.run(budget, body)` | Runs `body` with a deadline `budget` from now. A nested one ends at the earlier of the two, never later. |
| `RequestDeadline.runUntil(instant, body)` | The same, with an end time. |
| `RequestDeadline.current` | The deadline in force, or `null` outside any. |
| `remaining`, `isExpired` | What is left. |
| `check()` | Throws `RequestDeadlineExceededException` when it has passed. |

The web starter runs requests under one (`server.request-timeout`), and the Feign starter's calls stop at it. It works in the browser too. Spring has no counterpart: its timeouts are per call.

## PathPattern

Path patterns as Spring 6 parses them: `/books/{isbn}`, `{isbn:\d+}`, `{*rest}`, `*`, `?`, `**`.

| Member | Meaning |
|---|---|
| `PathPattern.parse(text)` | Parses a pattern. |
| `match(path)?.variables` | The path variables, or `null` when it does not match. |
| `matches(path)` | Whether it matches. |
| `combine(other)` | Joins a class pattern and a method pattern. |
| `compareTo` | Sorts the most specific first. |

A trailing slash matters, as in Spring 6.

## AllowedOrigins

The browser origins a server allows, checked as Spring checks `allowedOrigins` and `allowedOriginPatterns`: `checkOrigin(origin)` gives the `Access-Control-Allow-Origin` value or `null`. The web starter's CORS and the WebSocket starter's handshake check both use it.

- Origins are compared without case, patterns with case.
- Patterns take `*` (`https://*.shop.example`; a `*` matches any text, as Spring's `.*`, so `*.shop.example` takes any scheme) and a port list at the end (`http://localhost:[3000,3001]`, `[*]`: any port or none).
- Values may list several, separated by commas, and a trailing `/` is ignored.
- One difference from Spring: an origin longer than `maxOriginLength` (1024) characters is never allowed. Patterns are matched in time that grows with the origin's length (no backtracking regular expression).

## In Spring (Java)

The names follow Spring WebFlux's `ServerHttpRequest` / `ServerHttpResponse` and Spring MVC's `HandlerMapping`. `RequestDeadline` is an addition. Requests run in a `Zone` instead of on a thread.

## See also

- [Filters in the web starter](../spring-boot-starter-web/filters.md)
- [Handler mappings](../spring-boot-starter-web/server/handler-mappings.md)
- [Timeouts](../spring-boot-starter-web/server/timeouts.md)
