RequestExtraction extension

Reading values straight off the request.

An extractor is a value so a generator can name one, compose it, and check it. Written by hand that indirection is noise — the handler knows what it wants and it wants it from this request:

Future<Result<Todo, Rejection>> readTodo(Request request) async {
  final user = await request.extract<AuthUser>(const BearerAuth());
  final id = await request.path<String>('id');
  final repository = await request.state<TodoRepository>();

  final todo = repository.find(id);
  return todo == null || !user.mayActOn(todo.owner)
      ? const Err(_missing)
      : Ok(todo);
}

Every method throws the rejection an extractor produced rather than returning a Result, so the first failure ends the handler and the verb builder turns it into the response.

That makes this the wrong tool inside a custom extractor. An extract has to hand its failure back as Err, because a combinator that tries several extractors in turn reads the Result to decide whether to try the next one; a throw sails past it and ends the request. Use the extractor classes there:

// inside FromRequestParts.extract
switch (await const BearerTokenExtractable().extract(request)) {
  case Err(:final error):
    return Err(error);
  case Ok(value: final token):
    ...
}

In a handler, throwing is what you want; in an extractor, returning is.

on

Request

Methods

apiKey({String header = 'x-api-key', String query = 'api_key', bool allowQuery = true}) → Future<String>: Available on Request, provided by the RequestExtraction extension
An API key from a header, falling back to the query string.
basicCredentials({String realm = 'restricted'}) → Future<BasicCredentials>: Available on Request, provided by the RequestExtraction extension
The decoded username and password of an Authorization: Basic header.
bearerToken() → Future<String>: Available on Request, provided by the RequestExtraction extension
The token from an Authorization: Bearer header.
body<T>(T deserialize(Map<String, Object?> json)) → Future<T>: Available on Request, provided by the RequestExtraction extension
The JSON object body, decoded with deserialize.
bodyList<T>(T deserialize(Map<String, Object?> json)) → Future<List<T>>: Available on Request, provided by the RequestExtraction extension
The JSON array body, each element decoded with deserialize.
bodyStream() → Future<Stream<List<int>>>: Available on Request, provided by the RequestExtraction extension
The body as an unread stream, for a handler that owns its own limit.
cookie<T>(String name) → Future<T>: Available on Request, provided by the RequestExtraction extension
One cookie, coerced to T. A nullable T makes it optional.
cookies() → Future<CookieJar>: Available on Request, provided by the RequestExtraction extension
Every cookie at once.
extract<T>(FromRequestParts<T> extractor) → Future<T>: Available on Request, provided by the RequestExtraction extension
Runs extractor against this request.
form() → Future<FormMap>: Available on Request, provided by the RequestExtraction extension
The decoded fields of an application/x-www-form-urlencoded body.
header(String name) → Future<String?>: Available on Request, provided by the RequestExtraction extension
One header, or null when it is absent.
headerMap() → Future<Map<String, String>>: Available on Request, provided by the RequestExtraction extension
Every header at once, keyed by lower-case name.
host() → Future<String>: Available on Request, provided by the RequestExtraction extension
The Host header this request was addressed to.
multipart() → Future<MultipartForm>: Available on Request, provided by the RequestExtraction extension
The parts of a multipart/form-data body.
multipartStream({int limit = 64 * 1024 * 1024}) → Future<StreamedMultipart>: Available on Request, provided by the RequestExtraction extension
Hands the multipart body over a part at a time, without buffering it.
path<T>(String name) → Future<T>: Available on Request, provided by the RequestExtraction extension
The {name} path segment, coerced to T.
peer() → Future<PeerInfo>: Available on Request, provided by the RequestExtraction extension
The connection's peer address and port.
queries() → Future<Map<String, String>>: Available on Request, provided by the RequestExtraction extension
Every query pair at once.
query<T>(String name) → Future<T>: Available on Request, provided by the RequestExtraction extension
One query value, coerced to T.
queryList<T>(String name) → Future<List<T>>: Available on Request, provided by the RequestExtraction extension
Every value of a repeated query key, coerced to T.
rawBody() → Future<Uint8List>: Available on Request, provided by the RequestExtraction extension
The body as raw bytes.
rawQuery() → Future<String?>: Available on Request, provided by the RequestExtraction extension
The raw, undecoded query string, or null when there is none.
sessionId({String name = 'session'}) → Future<String>: Available on Request, provided by the RequestExtraction extension
A session identifier from a cookie, as 401 rather than 400 when absent.
state<T extends Object>() → Future<T>: Available on Request, provided by the RequestExtraction extension
The application state of type T attached with withState.
textBody() → Future<String>: Available on Request, provided by the RequestExtraction extension
The body as UTF-8 text.
validBody<T extends Validatable>(T deserialize(Map<String, Object?> json)) → Future<T>: Available on Request, provided by the RequestExtraction extension
The JSON object body, decoded and then checked against its constraints.

RequestExtraction extension

Methods

extraction library