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.

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