@adonisjs/http-server 6.8.2-6 → 6.8.2-8

package/build/src/request.js

@@ -1,3 +1,11 @@
+/*
+ * @adonisjs/http-server
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import fresh from 'fresh';
 import typeIs from 'type-is';
 import accepts from 'accepts';
@@ -11,20 +19,71 @@ import { createId } from '@paralleldrive/cuid2';
 import { parse } from 'node:url';
 import { trustProxy } from './helpers.js';
 import { CookieParser } from './cookies/parser.js';
+/**
+ * HTTP Request class exposes the interface to consistently read values
+ * related to a given HTTP request. The class is wrapper over
+ * [IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)
+ * and has extended API.
+ *
+ * You can access the original [IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)
+ * using `request.request` property.
+ */
 export class Request extends Macroable {
     request;
     response;
+    /**
+     * Query string parser
+     */
     #qsParser;
+    /**
+     * Encryption module to verify signed URLs and unsign/decrypt
+     * cookies
+     */
     #encryption;
+    /**
+     * Request config
+     */
     #config;
+    /**
+     * Request body set using `setBody` method
+     */
     #requestBody = {};
+    /**
+     * A merged copy of `request body` and `querystring`
+     */
     #requestData = {};
+    /**
+     * Original merged copy of `request body` and `querystring`.
+     * Further mutation to this object are not allowed
+     */
     #originalRequestData = {};
+    /**
+     * Parsed query string
+     */
     #requestQs = {};
+    /**
+     * Raw request body as text
+     */
     #rawRequestBody;
+    /**
+     * Cached copy of `accepts` fn to do content
+     * negotiation.
+     */
     #lazyAccepts;
+    /**
+     * Copy of lazily parsed signed and plain cookies.
+     */
     #cookieParser;
+    /**
+     * Parses copy of the URL with query string as a string and not
+     * object. This is done to build URL's with query string without
+     * stringifying the object
+     */
     parsedUrl;
+    /**
+     * The ctx will be set by the context itself. It creates a circular
+     * reference
+     */
     ctx;
     constructor(request, response, encryption, config, qsParser) {
         super();
@@ -36,20 +95,35 @@ export class Request extends Macroable {
         this.parsedUrl = parse(this.request.url, false);
         this.#parseQueryString();
     }
+    /**
+     * Parses the query string
+     */
     #parseQueryString() {
         if (this.parsedUrl.query) {
             this.updateQs(this.#qsParser.parse(this.parsedUrl.query));
             this.#originalRequestData = { ...this.#requestData };
         }
     }
+    /**
+     * Initiates the cookie parser lazily
+     */
     #initiateCookieParser() {
         if (!this.#cookieParser) {
             this.#cookieParser = new CookieParser(this.header('cookie'), this.#encryption);
         }
     }
+    /**
+     * Lazily initiates the `accepts` module to make sure to parse
+     * the request headers only when one of the content-negotiation
+     * methods are used.
+     */
     #initiateAccepts() {
         this.#lazyAccepts = this.#lazyAccepts || accepts(this.request);
     }
+    /**
+     * Returns the request id from the `x-request-id` header. The
+     * header is untouched, if it already exists.
+     */
     id() {
         let requestId = this.header('x-request-id');
         if (!requestId && this.#config.generateRequestId) {
@@ -58,66 +132,183 @@ export class Request extends Macroable {
         }
         return requestId;
     }
+    /**
+     * Set initial request body. A copy of the input will be maintained as the original
+     * request body. Since the request body and query string is subject to mutations, we
+     * keep one original reference to flash old data (whenever required).
+     *
+     * This method is supposed to be invoked by the body parser and must be called only
+     * once. For further mutations make use of `updateBody` method.
+     */
     setInitialBody(body) {
         if (this.#originalRequestData && Object.isFrozen(this.#originalRequestData)) {
             throw new Error('Cannot re-set initial body. Use "request.updateBody" instead');
         }
         this.updateBody(body);
+        /*
+         * Freeze the original object
+         */
         this.#originalRequestData = Object.freeze(lodash.cloneDeep(this.#requestData));
     }
+    /**
+     * Update the request body with new data object. The `all` property
+     * will be re-computed by merging the query string and request
+     * body.
+     */
     updateBody(body) {
         this.#requestBody = body;
         this.#requestData = { ...this.#requestBody, ...this.#requestQs };
     }
+    /**
+     * Update the request raw body. Bodyparser sets this when unable to parse
+     * the request body or when request is multipart/form-data.
+     */
     updateRawBody(rawBody) {
         this.#rawRequestBody = rawBody;
     }
+    /**
+     * Update the query string with the new data object. The `all` property
+     * will be re-computed by merging the query and the request body.
+     */
     updateQs(data) {
         this.#requestQs = data;
         this.#requestData = { ...this.#requestBody, ...this.#requestQs };
     }
+    /**
+     * Returns route params
+     */
     params() {
         return this.ctx?.params || {};
     }
+    /**
+     * Returns the query string object by reference
+     */
     qs() {
         return this.#requestQs;
     }
+    /**
+     * Returns reference to the request body
+     */
     body() {
         return this.#requestBody;
     }
+    /**
+     * Returns reference to the merged copy of request body
+     * and query string
+     */
     all() {
         return this.#requestData;
     }
+    /**
+     * Returns reference to the merged copy of original request
+     * query string and body
+     */
     original() {
         return this.#originalRequestData;
     }
+    /**
+     * Returns the request raw body (if exists), or returns `null`.
+     *
+     * Ideally you must be dealing with the parsed body accessed using [[input]], [[all]] or
+     * [[post]] methods. The `raw` body is always a string.
+     */
     raw() {
         return this.#rawRequestBody || null;
     }
+    /**
+     * Returns value for a given key from the request body or query string.
+     * The `defaultValue` is used when original value is `undefined`.
+     *
+     * @example
+     * ```js
+     * request.input('username')
+     *
+     * // with default value
+     * request.input('username', 'virk')
+     * ```
+     */
     input(key, defaultValue) {
         return lodash.get(this.#requestData, key, defaultValue);
     }
+    /**
+     * Returns value for a given key from route params
+     *
+     * @example
+     * ```js
+     * request.param('id')
+     *
+     * // with default value
+     * request.param('id', 1)
+     * ```
+     */
     param(key, defaultValue) {
         return lodash.get(this.params(), key, defaultValue);
     }
+    /**
+     * Get everything from the request body except the given keys.
+     *
+     * @example
+     * ```js
+     * request.except(['_csrf'])
+     * ```
+     */
     except(keys) {
         return lodash.omit(this.#requestData, keys);
     }
+    /**
+     * Get value for specified keys.
+     *
+     * @example
+     * ```js
+     * request.only(['username', 'age'])
+     * ```
+     */
     only(keys) {
         return lodash.pick(this.#requestData, keys);
     }
+    /**
+     * Returns the HTTP request method. This is the original
+     * request method. For spoofed request method, make
+     * use of [[method]].
+     *
+     * @example
+     * ```js
+     * request.intended()
+     * ```
+     */
     intended() {
         return this.request.method;
     }
+    /**
+     * Returns the request HTTP method by taking method spoofing into account.
+     *
+     * Method spoofing works when all of the following are true.
+     *
+     * 1. `app.http.allowMethodSpoofing` config value is true.
+     * 2. request query string has `_method`.
+     * 3. The [[intended]] request method is `POST`.
+     *
+     * @example
+     * ```js
+     * request.method()
+     * ```
+     */
     method() {
         if (this.#config.allowMethodSpoofing && this.intended() === 'POST') {
             return this.input('_method', this.intended()).toUpperCase();
         }
         return this.intended();
     }
+    /**
+     * Returns a copy of headers as an object
+     */
     headers() {
         return this.request.headers;
     }
+    /**
+     * Returns value for a given header key. The default value is
+     * used when original value is `undefined`.
+     */
     header(key, defaultValue) {
         key = key.toLowerCase();
         const headers = this.headers();
@@ -129,6 +320,37 @@ export class Request extends Macroable {
                 return headers[key] || defaultValue;
         }
     }
+    /**
+     * Returns the ip address of the user. This method is optimize to fetch
+     * ip address even when running your AdonisJs app behind a proxy.
+     *
+     * You can also define your own custom function to compute the ip address by
+     * defining `app.http.getIp` as a function inside the config file.
+     *
+     * ```js
+     * {
+     *   http: {
+     *     getIp (request) {
+     *       // I am using nginx as a proxy server and want to trust 'x-real-ip'
+     *       return request.header('x-real-ip')
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * You can control the behavior of trusting the proxy values by defining it
+     * inside the `config/app.js` file.
+     *
+     * ```js
+     * {
+     *   http: {
+     *    trustProxy: '127.0.0.1'
+     *   }
+     * }
+     * ```
+     *
+     * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+     */
     ip() {
         const ipFn = this.#config.getIp;
         if (typeof ipFn === 'function') {
@@ -136,9 +358,47 @@ export class Request extends Macroable {
         }
         return proxyaddr(this.request, this.#config.trustProxy);
     }
+    /**
+     * Returns an array of ip addresses from most to least trusted one.
+     * This method is optimize to fetch ip address even when running
+     * your AdonisJs app behind a proxy.
+     *
+     * You can control the behavior of trusting the proxy values by defining it
+     * inside the `config/app.js` file.
+     *
+     * ```js
+     * {
+     *   http: {
+     *    trustProxy: '127.0.0.1'
+     *   }
+     * }
+     * ```
+     *
+     * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+     */
     ips() {
         return proxyaddr.all(this.request, this.#config.trustProxy);
     }
+    /**
+     * Returns the request protocol by checking for the URL protocol or
+     * `X-Forwarded-Proto` header.
+     *
+     * If the `trust` is evaluated to `false`, then URL protocol is returned,
+     * otherwise `X-Forwarded-Proto` header is used (if exists).
+     *
+     * You can control the behavior of trusting the proxy values by defining it
+     * inside the `config/app.js` file.
+     *
+     * ```js
+     * {
+     *   http: {
+     *    trustProxy: '127.0.0.1'
+     *   }
+     * }
+     * ```
+     *
+     * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+     */
     protocol() {
         if ('encrypted' in this.request.socket) {
             return 'https';
@@ -149,11 +409,37 @@ export class Request extends Macroable {
         const forwardedProtocol = this.header('X-Forwarded-Proto');
         return forwardedProtocol ? forwardedProtocol.split(/\s*,\s*/)[0] : 'http';
     }
+    /**
+     * Returns a boolean telling if request is served over `https`
+     * or not. Check [[protocol]] method to know how protocol is
+     * fetched.
+     */
     secure() {
         return this.protocol() === 'https';
     }
+    /**
+     * Returns the request host. If proxy headers are trusted, then
+     * `X-Forwarded-Host` is given priority over the `Host` header.
+     *
+     * You can control the behavior of trusting the proxy values by defining it
+     * inside the `config/app.js` file.
+     *
+     * ```js
+     * {
+     *   http: {
+     *    trustProxy: '127.0.0.1'
+     *   }
+     * }
+     * ```
+     *
+     * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+     */
     host() {
         let host = this.header('host');
+        /*
+         * Use X-Fowarded-Host when we trust the proxy header and it
+         * exists
+         */
         if (trustProxy(this.request.socket.remoteAddress, this.#config.trustProxy)) {
             host = this.header('X-Forwarded-Host') || host;
         }
@@ -162,50 +448,125 @@ export class Request extends Macroable {
         }
         return host;
     }
+    /**
+     * Returns the request hostname. If proxy headers are trusted, then
+     * `X-Forwarded-Host` is given priority over the `Host` header.
+     *
+     * You can control the behavior of trusting the proxy values by defining it
+     * inside the `config/app.js` file.
+     *
+     * ```js
+     * {
+     *   http: {
+     *    trustProxy: '127.0.0.1'
+     *   }
+     * }
+     * ```
+     *
+     * The value of trustProxy is passed directly to [proxy-addr](https://www.npmjs.com/package/proxy-addr)
+     */
     hostname() {
         const host = this.host();
         if (!host) {
             return null;
         }
+        /*
+         * Support for IPv6
+         * https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2
+         * https://github.com/nodejs/node/pull/5314
+         */
         const offset = host[0] === '[' ? host.indexOf(']') + 1 : 0;
         const index = host.indexOf(':', offset);
         return index !== -1 ? host.substring(0, index) : host;
     }
+    /**
+     * Returns an array of subdomains for the given host. An empty array is
+     * returned if [[hostname]] is `null` or is an IP address.
+     *
+     * Also `www` is not considered as a subdomain
+     */
     subdomains() {
         const hostname = this.hostname();
+        /*
+         * Return empty array when hostname is missing or it's
+         * an IP address
+         */
         if (!hostname || isIP(hostname)) {
             return [];
         }
         const offset = this.#config.subdomainOffset;
         const subdomains = hostname.split('.').reverse().slice(offset);
+        /*
+         * Remove www from the subdomains list
+         */
         if (subdomains[subdomains.length - 1] === 'www') {
             subdomains.splice(subdomains.length - 1, 1);
         }
         return subdomains;
     }
+    /**
+     * Returns a boolean telling, if request `X-Requested-With === 'xmlhttprequest'`
+     * or not.
+     */
     ajax() {
         const xRequestedWith = this.header('X-Requested-With', '');
         return xRequestedWith.toLowerCase() === 'xmlhttprequest';
     }
+    /**
+     * Returns a boolean telling, if request has `X-Pjax` header
+     * set or not
+     */
     pjax() {
         return !!this.header('X-Pjax');
     }
+    /**
+     * Returns the request relative URL.
+     *
+     * @example
+     * ```js
+     * request.url()
+     *
+     * // include query string
+     * request.url(true)
+     * ```
+     */
     url(includeQueryString) {
         const pathname = this.parsedUrl.pathname;
         return includeQueryString && this.parsedUrl.query
             ? `${pathname}?${this.parsedUrl.query}`
             : pathname;
     }
+    /**
+     * Returns the complete HTTP url by combining
+     * [[protocol]]://[[hostname]]/[[url]]
+     *
+     * @example
+     * ```js
+     * request.completeUrl()
+     *
+     * // include query string
+     * request.completeUrl(true)
+     * ```
+     */
     completeUrl(includeQueryString) {
         const protocol = this.protocol();
         const hostname = this.host();
         return `${protocol}://${hostname}${this.url(includeQueryString)}`;
     }
+    /**
+     * Find if the current HTTP request is for the given route or the routes
+     */
     matchesRoute(routeIdentifier) {
+        /**
+         * The context is missing inside the HTTP server hooks.
+         */
         if (!this.ctx || !this.ctx.route) {
             return false;
         }
         const route = this.ctx.route;
+        /**
+         * Search the identifier(s) against the route "pattern", "name" and the route handler
+         */
         return !!(Array.isArray(routeIdentifier) ? routeIdentifier : [routeIdentifier]).find((identifier) => {
             if (route.pattern === identifier || route.name === identifier) {
                 return true;
@@ -216,44 +577,197 @@ export class Request extends Macroable {
             return route.handler.reference === identifier;
         });
     }
+    /**
+     * Returns the best matching content type of the request by
+     * matching against the given types.
+     *
+     * The content type is picked from the `content-type` header and request
+     * must have body.
+     *
+     * The method response highly depends upon the types array values. Described below:
+     *
+     * | Type(s) | Return value |
+     * |----------|---------------|
+     * | ['json'] | json |
+     * | ['application/*'] | application/json |
+     * | ['vnd+json'] | application/json |
+     *
+     * @example
+     * ```js
+     * const bodyType = request.is(['json', 'xml'])
+     *
+     * if (bodyType === 'json') {
+     *  // process JSON
+     * }
+     *
+     * if (bodyType === 'xml') {
+     *  // process XML
+     * }
+     * ```
+     */
     is(types) {
         return typeIs(this.request, types) || null;
     }
+    /**
+     * Returns the best type using `Accept` header and
+     * by matching it against the given types.
+     *
+     * If nothing is matched, then `null` will be returned
+     *
+     * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
+     * docs too.
+     *
+     * @example
+     * ```js
+     * switch (request.accepts(['json', 'html'])) {
+     *   case 'json':
+     *     return response.json(user)
+     *   case 'html':
+     *     return view.render('user', { user })
+     *   default:
+     *     // decide yourself
+     * }
+     * ```
+     */
     accepts(types) {
         this.#initiateAccepts();
         return this.#lazyAccepts.type(types) || null;
     }
+    /**
+     * Return the types that the request accepts, in the order of the
+     * client's preference (most preferred first).
+     *
+     * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
+     * docs too.
+     */
     types() {
         this.#initiateAccepts();
         return this.#lazyAccepts.types();
     }
+    /**
+     * Returns the best language using `Accept-language` header
+     * and by matching it against the given languages.
+     *
+     * If nothing is matched, then `null` will be returned
+     *
+     * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
+     * docs too.
+     *
+     * @example
+     * ```js
+     * switch (request.language(['fr', 'de'])) {
+     *   case 'fr':
+     *     return view.render('about', { lang: 'fr' })
+     *   case 'de':
+     *     return view.render('about', { lang: 'de' })
+     *   default:
+     *     return view.render('about', { lang: 'en' })
+     * }
+     * ```
+     */
     language(languages) {
         this.#initiateAccepts();
         return this.#lazyAccepts.language(languages) || null;
     }
+    /**
+     * Return the languages that the request accepts, in the order of the
+     * client's preference (most preferred first).
+     *
+     * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
+     * docs too.
+     */
     languages() {
         this.#initiateAccepts();
         return this.#lazyAccepts.languages();
     }
+    /**
+     * Returns the best charset using `Accept-charset` header
+     * and by matching it against the given charsets.
+     *
+     * If nothing is matched, then `null` will be returned
+     *
+     * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
+     * docs too.
+     *
+     * @example
+     * ```js
+     * switch (request.charset(['utf-8', 'ISO-8859-1'])) {
+     *   case 'utf-8':
+     *     // make utf-8 friendly response
+     *   case 'ISO-8859-1':
+     *     // make ISO-8859-1 friendly response
+     * }
+     * ```
+     */
     charset(charsets) {
         this.#initiateAccepts();
         return this.#lazyAccepts.charset(charsets) || null;
     }
+    /**
+     * Return the charsets that the request accepts, in the order of the
+     * client's preference (most preferred first).
+     *
+     * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
+     * docs too.
+     */
     charsets() {
         this.#initiateAccepts();
         return this.#lazyAccepts.charsets();
     }
+    /**
+     * Returns the best encoding using `Accept-encoding` header
+     * and by matching it against the given encodings.
+     *
+     * If nothing is matched, then `null` will be returned
+     *
+     * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
+     * docs too.
+     */
     encoding(encodings) {
         this.#initiateAccepts();
         return this.#lazyAccepts.encoding(encodings) || null;
     }
+    /**
+     * Return the charsets that the request accepts, in the order of the
+     * client's preference (most preferred first).
+     *
+     * Make sure to check [accepts](https://www.npmjs.com/package/accepts) package
+     * docs too.
+     */
     encodings() {
         this.#initiateAccepts();
         return this.#lazyAccepts.encodings();
     }
+    /**
+     * Returns a boolean telling if request has body
+     */
     hasBody() {
         return typeIs.hasBody(this.request);
     }
+    /**
+     * Returns a boolean telling if the new response etag evaluates same
+     * as the request header `if-none-match`. In case of `true`, the
+     * server must return `304` response, telling the browser to
+     * use the client cache.
+     *
+     * You won't have to deal with this method directly, since AdonisJs will
+     * handle this for you when `http.etag = true` inside `config/app.js` file.
+     *
+     * However, this is how you can use it manually.
+     *
+     * ```js
+     * const responseBody = view.render('some-view')
+     *
+     * // sets the HTTP etag header for response
+     * response.setEtag(responseBody)
+     *
+     * if (request.fresh()) {
+     *   response.sendStatus(304)
+     * } else {
+     *   response.send(responseBody)
+     * }
+     * ```
+     */
     fresh() {
         if (['GET', 'HEAD'].indexOf(this.intended()) === -1) {
             return false;
@@ -264,17 +778,32 @@ export class Request extends Macroable {
         }
         return false;
     }
+    /**
+     * Opposite of [[fresh]]
+     */
     stale() {
         return !this.fresh();
     }
+    /**
+     * Returns all parsed and signed cookies. Signed cookies ensures
+     * that their value isn't tampered.
+     */
     cookiesList() {
         this.#initiateCookieParser();
         return this.#cookieParser.list();
     }
+    /**
+     * Returns value for a given key from signed cookies. Optional
+     * defaultValue is returned when actual value is undefined.
+     */
     cookie(key, defaultValue) {
         this.#initiateCookieParser();
         return this.#cookieParser.unsign(key) || defaultValue;
     }
+    /**
+     * Returns value for a given key from signed cookies. Optional
+     * defaultValue is returned when actual value is undefined.
+     */
     encryptedCookie(key, defaultValue) {
         this.#initiateCookieParser();
         return this.#cookieParser.decrypt(key) || defaultValue;
@@ -287,11 +816,18 @@ export class Request extends Macroable {
         }
         return this.#cookieParser.decode(key, encoded) || defaultValueOrOptions;
     }
+    /**
+     * Returns a boolean telling if a signed url as a valid signature
+     * or not.
+     */
     hasValidSignature(purpose) {
         const { signature, ...rest } = this.qs();
         if (!signature) {
             return false;
         }
+        /*
+         * Return false when signature fails
+         */
         const signedUrl = this.#encryption.verifier.unsign(signature, purpose);
         if (!signedUrl) {
             return false;
@@ -301,6 +837,9 @@ export class Request extends Macroable {
             ? safeEqual(signedUrl, `${this.url()}?${queryString}`)
             : safeEqual(signedUrl, this.url());
     }
+    /**
+     * Serializes request to JSON format
+     */
     serialize() {
         return {
             id: this.id(),
@@ -317,6 +856,9 @@ export class Request extends Macroable {
             subdomains: this.ctx?.subdomains || {},
         };
     }
+    /**
+     * toJSON copy of the request
+     */
     toJSON() {
         return this.serialize();
     }