request.ts

/**
 * @adonisjs/http-server
 *
 * (c) Harminder Virk <virk@adonisjs.com>
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

declare module '@ioc:Adonis/Core/Request' {
  import { UrlWithStringQuery } from 'url'
  import { MacroableConstructorContract } from 'macroable'
  import { EncryptionContract } from '@ioc:Adonis/Core/Encryption'
  import { HttpContextContract } from '@ioc:Adonis/Core/HttpContext'
  import { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'http'

  /**
   * Shape of the request class instance
   */
  export interface RequestContract {
    /**
     * 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: UrlWithStringQuery

    request: IncomingMessage
    response: ServerResponse

    /**
     * The ctx will be set by the context itself. It creates a circular
     * reference
     */
    ctx?: HttpContextContract

    /**
     * Returns the request id from the `x-request-id` header. The
     * header is untoched, if it already exists.
     */
    id (): string | undefined

    /**
     * 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: any): void

    /**
     * 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: any): void

    /**
     * Update the request raw body. Bodyparser sets this when unable to parse
     * the request body or when request is multipart/form-data.
     */
    updateRawBody (body: string): void

    /**
     * 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: any): void

    /**
     * Returns reference to the query string object
     */
    get (): { [key: string]: any }

    /**
     * Returns reference to the request body
     */
    post (): { [key: string]: any }

    /**
     * Returns reference to the merged copy of original request
     * query string and body
     */
    original (): { [key: string]: any }

    /**
     * Returns reference to the merged copy of request body
     * and query string
     */
    all (): { [key: string]: any }

    /**
     * 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 (): string | 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: string, defaultValue?: any): any

    /**
     * Get everything from the request body except the given keys.
     *
     * @example
     * ```js
     * request.except(['_csrf'])
     * ```
     */
    except (keys: string[]): { [key: string]: any }

    /**
     * Get value for specified keys.
     *
     * @example
     * ```js
     * request.only(['username', 'age'])
     * ```
     */
    only<T extends string, U = { [K in T]: any }> (keys: T[]): U

    /**
     * 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 (): string

    /**
     * Returns the HTTP request method. This is the original
     * request method. For spoofed request method, make
     * use of [[method]].
     *
     * @example
     * ```js
     * request.intended()
     * ```
     */
    intended (): string

    /**
     * Returns a copy of headers as an object
     */
    headers (): IncomingHttpHeaders

    /**
     * Returns value for a given header key. The default value is
     * used when original value is `undefined`.
     */
    header (key: string, defaultValue?: any): string | undefined

    /**
     * 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 (): string

    /**
     * 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 (): string[]

    /**
     * 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 (): string

    /**
     * Returns a boolean telling if request is served over `https`
     * or not. Check [[protocol]] method to know how protocol is
     * fetched.
     */
    secure (): boolean

    /**
     * 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 (): string[]

    /**
     * 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 (): string | null

    /**
     * Returns a boolean telling, if request `X-Requested-With === 'xmlhttprequest'`
     * or not.
     */
    ajax (): boolean

    /**
     * Returns a boolean telling, if request has `X-Pjax` header
     * set or not
     */
    pjax (): boolean

    /**
     * Returns the request relative URL.
     *
     * @example
     * ```js
     * request.url()
     *
     * // include query string
     * request.url(true)
     * ```
     */
    url (includeQueryString?: boolean): string

    /**
     * Returns the complete HTTP url by combining
     * [[protocol]]://[[hostname]]/[[url]]
     *
     * @example
     * ```js
     * request.completeUrl()
     *
     * // include query string
     * request.completeUrl(true)
     * ```
     */
    completeUrl (includeQueryString?: boolean): string

    /**
     * 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: string[]): string | 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 <T extends string> (types: T[]): T | 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 (): string[]

    /**
     * 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 <T extends string> (languages: T[]): T | 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 (): string[]

    /**
     * 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 <T extends string> (encodings: T[]): T | 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 (): string[]

    /**
     * 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 <T extends string> (charsets: T[]): T | 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 (): string[]

    /**
     * Returns a boolean telling if request has body
     */
    hasBody (): boolean

    /**
     * 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.
     *
     * @example
     * ```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 (): boolean

    /**
     * Opposite of [[fresh]]
     */
    stale (): boolean

    /**
     * Returns all parsed and signed cookies. Signed cookies ensures
     * that their value isn't tampered.
     */
    cookiesList (): { [key: string]: any }

    /**
     * Returns value for a given key from signed cookies. Optional
     * defaultValue is returned when actual value is undefined.
     */
    cookie (key: string, defaultValue?: any): any

    /**
     * Returns value for a given key from signed cookies. Optional
     * defaultValue is returned when actual value is undefined.
     */
    encryptedCookie (key: string, defaultValue?: any): any

    /**
     * Returns value for a given key from unsigned cookies. Optional
     * defaultValue is returned when actual value is undefined.
     */
    plainCookie (key: string, defaultValue?: any): any

    /**
     * Returns a boolean telling if a signed url as a valid signature
     * or not.
     */
    hasValidSignature (purpose?: string): boolean

    /**
     * toJSON copy of the request
     */
    toJSON (): any
  }

  /**
   * Shape of the request config
   */
  export type RequestConfig = {
    forceContentNegotiationToJSON?: boolean,
    subdomainOffset: number,
    generateRequestId: boolean,
    allowMethodSpoofing: boolean,
    getIp?: ((request: RequestContract) => string),
    trustProxy: (address: string, distance: number) => boolean,
    enableAsyncHttpContext?: boolean,
  }

  /**
   * Shape of request constructor, we export the constructor for others to
   * add macros to the request class. Since, the instance is passed
   * to the http request cycle
   */
  export interface RequestConstructorContract extends MacroableConstructorContract<RequestContract> {
    new (
      request: IncomingMessage,
      response: ServerResponse,
      encryption: EncryptionContract,
      config: RequestConfig,
    ): RequestContract
  }

  const Request: RequestConstructorContract
  export default Request
}