ServerHttpRequest class abstract interface

An HTTP request received by the application: method, URL, headers, cookies and a body that can be read once.

It hides which server received the request: the web starter's dart:io server and MockMvc (with a MockServerHttpRequest) both provide one, so filters and controllers run the same in production and in tests.

Most controllers never touch it: they take the values they need with @PathVariable, @RequestParam, @RequestHeader or @RequestBody. Declare a parameter of this type when a method needs the raw request; a WebFilter or a HandlerMapping always works with it.

// A controller method that needs the client's address and a header.
@GetMapping('/whoami')
String whoami(ServerHttpRequest request) =>
    '${request.remoteAddress} ${request.headers['User-Agent']}';

Spring (Java): ServerHttpRequest (Spring WebFlux), or HttpServletRequest on the servlet stack:

@GetMapping("/whoami")
String whoami(HttpServletRequest request) {
  return request.getRemoteAddr() + " " + request.getHeader("User-Agent");
}
Implementers
Available extensions

Properties

attributes → Map<String, Object?>
A mutable map where filters and handlers leave values for the code that runs later on the same request, such as a parsed form or a trace id. It lives as long as the request.
no setter
body → Stream<Uint8List>
The body as a stream of bytes. It can be listened to only once: a second read throws a StateError. On the web starter's server a body above server.max-http-request-body-size ends with a PayloadTooLargeException, whatever its Content-Type (the starter's multipart resolver reads uploads with their own limit, spring.web.multipart.max-request-size). For small bodies, ServerHttpRequestBody.readBodyBytes and ServerHttpRequestBody.readBodyText are simpler.
no setter
contentType → MediaType?

Available on ServerHttpRequest, provided by the ServerHttpRequestBody extension

The Content-Type header parsed, or null when it is missing or is not a valid media type.
no setter
cookies → Map<String, String>
The cookies of the Cookie header, by name (quotes around a value removed).
no setter
hashCode → int
The hash code for this object.
no setterinherited
headers → HttpHeaders
The headers the client sent. Treat them as read-only; to change them for the rest of the chain, wrap the request in a ServerHttpRequestDecorator.
no setter
isSecure → bool
Whether the request came over TLS (https or wss).
no setter
isWebSocketUpgrade → bool
Whether the client asks to open a WebSocket on this request (Upgrade: websocket).
no setter
method → HttpMethod
The HTTP method of the request.
no setter
path → String
The path without the query, still percent-encoded (/api/books/978-0). Behind a server.context-path, filters and handlers see the path without that prefix.
no setter
principal ↔ Principal?
The authenticated user or client, or null while nobody is authenticated. An authentication filter (for example the security starter's) sets it; a controller parameter of type Principal receives it.
getter/setter pair
queryParameters → Map<String, List<String>>
The query parameters, decoded, each name with all its values in order (?tag=a&tag=b gives {'tag': ['a', 'b']}).
no setter
remoteAddress → String?
The IP address of the client, or null when the server does not know it. Behind a proxy this is the proxy's address.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
uri → Uri
The full URL as the client asked for it: scheme, host, port, path and query (on the web starter's server, the host is the one of the Host header).
no setter

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
readBodyBytes({int? maxLength}) → Future<Uint8List>

Available on ServerHttpRequest, provided by the ServerHttpRequestBody extension

Reads the whole body into memory. Throws a PayloadTooLargeException as soon as it grows past maxLength bytes (no limit when null). Like ServerHttpRequest.body, it can be called only once.
readBodyText({int? maxLength}) → Future<String>

Available on ServerHttpRequest, provided by the ServerHttpRequestBody extension

Reads the whole body as text, decoded with the charset of the Content-Type: ISO-8859-1 and US-ASCII are recognised, anything else (or no charset) is read as UTF-8, with malformed bytes replaced. maxLength limits the size in bytes as in readBodyBytes.
toString() → String
A string representation of this object.
inherited
upgradeToWebSocket({String? protocol}) → Future<WebSocketSession>
Accepts the WebSocket handshake and returns the open connection.

Operators

operator ==(Object other) → bool
The equality operator.
inherited