requests

introduction

the Request class wraps the raw node http request to provide an api for interacting with incoming data. it parses the url, query strings, headers, and body payloads (json, formn urlencoded, and multipart files).

in controllers and middleware, the request instance is injected as the req argument.

the request context

the framework utilizes AsyncLocalStorage to maintain request state across the entire asynchronous call stack. this allows you to access the current request globally without passing the req object down through every function.

1import { RequestContext } from 'dframework';
2 
3function getClientIp() {
4  const req = RequestContext.get();
5  return req ? req.headers['x-forwarded-for'] || req.socket.remoteAddress : null;
6}

request identity

the request object provides several getters to determine the origin and format of the request.

1// returns true if the request comes from native builds
2if (req.isNative) {
3  return json({ success: true, native: true });
4}
5 
6// returns true for XMLHttpRequest, dSPAHttpRequest, or application/json accept headers
7if (req.isAjax) {
8  return abort(422, 'validation failed');
9}
10 
11// returns true specifically for the framework's client side spa router
12if (req.isSPA) {
13  return json({ component: 'Home' });
14}

input and parameters

the framework lazily parses input to avoid overhead on routes that don't need it.

1// parsed from the query string (e.g. ?search=term)
2const query = req.query.search;
3 
4// parsed from the cookie header
5const locale = req.cookies.locale;
6 
7// automatically extracts and ensures 'page' is an integer, defaulting to 1
8const page = req.page;

as detailed in the controllers documentation, req.body and req.files are populated automatically for mutating requests (POST, PUT, PATCH, DELETE) by the route compiler.

headers

you can retrieve headers using the header() or get() methods, which are case insensitive.

1const userAgent = req.header('user-agent');
2const referer = req.header('referrer'); // handles both referer and referrer

csrf management

the request object handles generating and verifying csrf tokens. the route compiler automatically inserts verification logic for all mutating routes unless explicitly disabled, so you rarely call these methods manually.

1// generate a new token valid for 6 hours
2const token = req.csrfToken();
3 
4// verify a submitted token
5const isValid = req.verifyCsrfToken(submittedToken);
6 
7// force rotation of the current token
8const newToken = req.rotateCsrfToken();