extraction library

Extractors: turning a request into the values a handler declares.

Import this when writing a custom extractor, or when calling the built-ins by hand rather than through generated code.

import 'package:dust_server/extraction.dart';

final class BearerAuth implements FromRequestParts<AuthUser> {
  const BearerAuth();

  @override
  Future<Result<AuthUser, Rejection>> extract(Request request) async { ... }
}

Everything here is also exported from package:dust_server/server.dart.

Classes

ApiKeyExtractable
Extracts an API key from a header, falling back to the query string.
Authorization
An Authorization header, split where the specification splits it.
BasicCredentials
A username and password from an Authorization: Basic header.
BasicCredentialsExtractable
Extracts and decodes an Authorization: Basic base64(user:password) header.
BearerTokenExtractable
Extracts the token from an Authorization: Bearer <token> header.
ContextExtractable<T>
Extracts a value middleware stored in the shelf request context.
CookieExtractable<T>
Extracts one cookie, coerced to T.
CookieJar
The cookies one request carried.
CookieJarExtractable
Extracts every cookie at once.
Err<T, E>
Failed operation result.
FallibleExtractable<T>
Hands the rejection to the handler instead of short-circuiting.
FirstOf<T>
Tries each extractor in order and takes the first that succeeds.
FormExtractable
Decodes an application/x-www-form-urlencoded body.
FormMap
The decoded fields of a form body.
FromRequest<T>
Marks an extractor that reads the request body.
FromRequestParts<T>
Builds a T from a request, or rejects it.
HeaderExtractable<T>
Extracts one header, coerced to T.
HeaderMapExtractable
Extracts every header as a map with lower-case keys.
HostExtractable
The host a request was addressed to.
JsonExtractable<T>
Decodes a JSON object body into T.
JsonListExtractable<T>
Decodes a JSON array body into List<T>.
MatchedRouteSlot
A box a layer passes down so the router can report back what it matched.
MultipartExtractable
Decodes a multipart/form-data body.
MultipartForm
The decoded parts of a multipart/form-data body.
MultipartPart
One part of a multipart body, still arriving.
None<T>
Option state for an absent value.
Ok<T, E>
Successful operation result.
Option<T>
Optional value wrapper for Rust-style present-or-absent values.
OptionalExtractable<T>
Turns a client-error rejection into None.
PathExtractable<T>
Extracts one router-captured path parameter, coerced to T.
PeerExtractable
Extracts the connection information for this request.
PeerInfo
The peer address and port of the connection serving this request.
QueriesExtractable<T>
Extracts every query value as a map.
QueryExtractable<T>
Extracts one query value, coerced to T.
QueryListExtractable<T>
Extracts every value for one repeated query key, coerced to T.
RawBodyExtractable
Reads the body as raw bytes, with no media type requirement.
RawQueryExtractable
Extracts the raw, undecoded query string.
Request
An HTTP request to be processed by a Shelf application.
RequestParts
The non-body half of a request.
Result<T, E>
Result of an operation that can either succeed with T or fail with E.
SessionIdExtractable
Extracts a session identifier from a cookie.
Some<T>
Option state for a present value.
StateExtractable<T extends Object>
Reads application state attached with Router.withState.
StreamBodyExtractable
Hands the body to the handler as an unread stream.
StreamedMultipart
A multipart body, delivered a part at a time.
StreamedMultipartExtractable
Hands a multipart/form-data body to the handler a part at a time.
TextBodyExtractable
Reads the body as UTF-8 text.
Unit
Empty success value for operations that only signal completion.
UploadedFile
One decoded part of a multipart body.
ValidatedExtractable<T extends Validatable>
Runs the Validate() constraints after inner builds the value.

Extensions

OptionCombine on Option<T>
Combining Option values, and moving between Option and Result.
OptionFlatten on Option<Option<T>>
Removing one level of Option nesting.
OptionQuery on Option<T>
Reading an Option without matching on it.
OptionTransform on Option<T>
Transforming and choosing between Option values.
OptionTranspose on Option<Result<T, E>>
Swapping an Option of a Result inside out.
OptionUnzip on Option<(A, B)>
Splitting an Option of a pair.
RejectOnFailure on Result<T, Rejection>
Collapses an extraction outcome onto its value.
RequestExtraction on Request
Reading values straight off the request.
RequireExtraction on FromRequestParts<T>
Runs an extractor and throws the rejection instead of returning it.

Constants

bodyLimitContextKey → const String
The context key carrying the active body limit.
defaultBodyLimit → const int
The default maximum body size, in bytes.
matchedPathKey → const String
The context key the matched route pattern travels under.
matchedRouteSlotKey → const String
The context key a MatchedRouteSlot travels under.
pathParametersKey → const String
The context key captured path parameters travel under.
unit → const Unit
Shared unit value.

Functions

apiKey({String header = 'x-api-key', String query = 'api_key', bool allowQuery = true}) → FromRequestParts<String>
Reads an API key from a header, falling back to the query string.
basicCredentials({String realm = 'restricted'}) → FromRequestParts<BasicCredentials>
Reads and decodes an Authorization: Basic header.
bearerToken() → FromRequestParts<String>
Reads the token from an Authorization: Bearer header.
body<T>(T deserialize(Map<String, Object?> json)) → FromRequest<T>
Decodes a JSON object body with deserialize.
bodyList<T>(T deserialize(Map<String, Object?> json)) → FromRequest<List<T>>
Decodes a JSON array body with deserialize.
bodyStream() → FromRequest<Stream<List<int>>>
Hands the body to the handler as an unread stream.
coerce<T>(String raw, {required String source}) → Result<T, Rejection>
Converts one raw string from a path segment, query value, header, or form field into T.
Reads one cookie, coerced to T. A nullable T makes it optional.
cookies() → FromRequestParts<CookieJar>
Reads every cookie at once.
effectiveBodyLimit(Request request, int limit) → int
The smaller of limit and whatever the router configured.
fallible<T>(FromRequestParts<T> inner) → FromRequestParts<Result<T, Rejection>>
Hands inner's rejection to the handler instead of short-circuiting.
firstOf<T>(List<FromRequestParts<T>> extractors) → FromRequestParts<T>
Takes whichever of extractors succeeds first.
form() → FromRequest<FormMap>
Decodes an application/x-www-form-urlencoded body.
Reads one header, or null when it is absent.
headers() → FromRequestParts<Map<String, String>>
Reads every header at once.
host() → FromRequestParts<String>
Reads the Host header, which the client controls — compare, do not trust.
isJsonMediaType(String? mediaType) → bool
Whether mediaType is JSON or a +json structured syntax suffix.
matchedPathOf(Request request) → String?
The route pattern that matched request, or null when none did.
multipart() → FromRequest<MultipartForm>
Decodes a multipart/form-data body, buffering every part.
multipartStream({int limit = 64 * 1024 * 1024}) → FromRequest<StreamedMultipart>
Hands a multipart/form-data body over a part at a time, without buffering.
optional<T>(FromRequestParts<T> inner) → FromRequestParts<Option<T>>
Turns a client-error rejection from inner into None.
path<T>(String name) → FromRequestParts<T>
Reads the {name} path segment, coerced to T.
pathParametersOf(Request request) → Map<String, String>
Reads router-captured path parameters from request.
peer() → FromRequestParts<PeerInfo>
The connection's peer address and port.
queries() → FromRequestParts<Map<String, String>>
Reads every query pair at once.
query<T>(String name) → FromRequestParts<T>
Reads one query value, coerced to T. A nullable T makes it optional.
queryList<T>(String name) → FromRequestParts<List<T>>
Reads every value of a repeated query key, coerced to T.
rawBody() → FromRequest<Uint8List>
Reads the body as raw bytes.
rawQuery() → FromRequestParts<String?>
Reads the raw, undecoded query string, or null when there is none.
rawRequest() → FromRequestParts<Request>
The request itself, for a handler that wants to reach past the extractors.
readBody(Request request, {int limit = defaultBodyLimit}) → Future<Result<Uint8List, Rejection>>
Reads the whole request body, rejecting with 413 past limit.
readsRequestBody(FromRequestParts<Object?> extractor) → bool
Whether extractor ends up reading the request body.
reportMatchedRoute(Request request, String route) → void
Fills the slot request carries, when it carries one.
sessionId({String name = 'session'}) → FromRequestParts<String>
Reads a session identifier from a cookie.
state<T extends Object>() → FromRequestParts<T>
Reads the application state of type T attached with withState.
stateKeyFor<T>() → String
The request-context key state of type T travels under.
stateMiddleware(Map<String, Object> state) → Middleware?
Builds the middleware that puts state on every request below a group.
textBody() → FromRequest<String>
Reads the body as UTF-8 text.
typeOf<X>() → Type
Reifies X so nullable targets can be compared, since T == String? is not valid syntax.
valid<T extends Validatable>(FromRequestParts<T> inner) → FromRequestParts<T>
Runs the generated validate after inner builds the value.