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
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.exampletakes 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.