@types/restify/index.d.ts

// Type definitions for restify 8.5
// Project: https://github.com/restify/node-restify, http://restify.com
// Definitions by: Bret Little <https://github.com/blittle>
//                 Steve Hipwell <https://github.com/stevehipwell>
//                 Leandro Almeida <https://github.com/leanazulyoro>
//                 Mitchell Bundy <https://github.com/mgebundy>
//                 Alexandre Moraes <https://github.com/alcmoraes>
//                 Quinn Langille <https://github.com/quinnlangille>
//                 Gaikwad Pratik <https://github.com/GaikwadPratik>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// TypeScript Version: 2.2

/// <reference types="node" />
import http = require('http');
import https = require('https');
import Logger = require('bunyan');
import url = require('url');
import spdy = require('spdy');
import stream = require('stream');
import zlib = require('zlib');
import { File } from 'formidable';

export interface ServerOptions {
    ca?: string | Buffer | ReadonlyArray<string | Buffer> | undefined;

    certificate?: string | Buffer | ReadonlyArray<string | Buffer> | undefined;

    cert?: string | Buffer | ReadonlyArray<string | Buffer> | undefined;

    key?: string | Buffer | ReadonlyArray<string | Buffer> | undefined;

    passphrase?: string | undefined;

    requestCert?: boolean | undefined;

    ciphers?: string | undefined;

    formatters?: Formatters | undefined;

    log?: Logger | undefined;

    name?: string | undefined;

    spdy?: spdy.ServerOptions | undefined;

    version?: string | undefined;

    versions?: string[] | undefined;

    handleUpgrades?: boolean | undefined;

    httpsServerOptions?: https.ServerOptions | undefined;

    handleUncaughtExceptions?: boolean | undefined;

    router?: Router | undefined;

    socketio?: boolean | undefined;

    noWriteContinue?: boolean | undefined;

    rejectUnauthorized?: boolean | undefined;

    secureOptions?: number | undefined;

    http2?: any;

    dtrace?: boolean | undefined;

    onceNext?: boolean | undefined;

    strictNext?: boolean | undefined;

    ignoreTrailingSlash?: boolean | undefined;

    maxParamLength?: number | undefined;
}

export interface AddressInterface {
    port: number;

    family: string;

    address: string;
}

export interface Server extends http.Server {
    /**
     * Returns the server address. Wraps node's address().
     */
    address(): AddressInterface;

    /**
     * Gets the server up and listening. Wraps node's listen().
     *
     * You can call like:
     *  server.listen(80)
     *  server.listen(80, '127.0.0.1')
     *  server.listen('/tmp/server.sock')
     *
     * @throws   {TypeError}
     * @param     callback optionally get notified when listening.
     */
    listen(...args: any[]): any;

    /**
     * Shuts down this server, and invokes callback (optionally) when done.
     * Wraps node's close().
     * @param     callback optional callback to invoke when done.
     */
    close(callback?: () => any): any;

    /**
     * Returns the number of currently inflight requests.
     */
    inflightRequests(): number;

    /**
     * Mounts a chain on the given path against this HTTP verb
     *
     * @param   opts if string, the URL to handle.
     *                                 if options, the URL to handle, at minimum.
     * @returns                the newly created route.
     */
    del(opts: string | RegExp | RouteOptions, ...handlers: RequestHandlerType[]): Route | boolean;

    /**
     * Mounts a chain on the given path against this HTTP verb
     *
     * @param   opts if string, the URL to handle.
     *                                 if options, the URL to handle, at minimum.
     * @returns                the newly created route.
     */
    get(opts: string | RegExp | RouteOptions, ...handlers: RequestHandlerType[]): Route | boolean;

    /**
     * Mounts a chain on the given path against this HTTP verb
     *
     * @param   opts if string, the URL to handle.
     *                                 if options, the URL to handle, at minimum.
     * @returns                the newly created route.
     */
    head(opts: string | RegExp | RouteOptions, ...handlers: RequestHandlerType[]): Route | boolean;

    /**
     * Mounts a chain on the given path against this HTTP verb
     *
     * @param   opts if string, the URL to handle.
     *                                 if options, the URL to handle, at minimum.
     * @returns                the newly created route.
     */
    opts(opts: string | RegExp | RouteOptions, ...handlers: RequestHandlerType[]): Route | boolean;

    /**
     * Mounts a chain on the given path against this HTTP verb
     *
     * @param   opts if string, the URL to handle.
     *                                 if options, the URL to handle, at minimum.
     * @returns                the newly created route.
     */
    post(opts: string | RegExp | RouteOptions, ...handlers: RequestHandlerType[]): Route | boolean;

    /**
     * Mounts a chain on the given path against this HTTP verb
     *
     * @param   opts if string, the URL to handle.
     *                                 if options, the URL to handle, at minimum.
     * @returns                the newly created route.
     */
    put(opts: string | RegExp | RouteOptions, ...handlers: RequestHandlerType[]): Route | boolean;

    /**
     * Mounts a chain on the given path against this HTTP verb
     *
     * @param   opts if string, the URL to handle.
     *                                 if options, the URL to handle, at minimum.
     * @returns                the newly created route.
     */
    patch(opts: string | RegExp | RouteOptions, ...handlers: RequestHandlerType[]): Route | boolean;

    /**
     * Minimal port of the functionality offered by Express.js Route Param
     * Pre-conditions
     * @link http://expressjs.com/guide.html#route-param%20pre-conditions
     *
     * This basically piggy-backs on the `server.use` method. It attaches a
     * new middleware function that only fires if the specified parameter exists
     * in req.params
     *
     * Exposes an API:
     *   server.param("user", function (req, res, next) {
     *     // load the user's information here, always making sure to call next()
     *   });
     *
     * @param      name The name of the URL param to respond to
     * @param    fn   The middleware function to execute
     * @returns         returns self
     */
    param(name: string, fn: RequestHandler): Server;

    /**
     * Removes a route from the server.
     * You pass in the route 'blob' you got from a mount call.
     * @throws   {TypeError} on bad input.
     * @param       route the route name.
     * @returns          true if route was removed, false if not.
     */
    rm(route: string): boolean;

    /**
     * Installs a list of handlers to run _before_ the "normal" handlers of all
     * routes.
     *
     * You can pass in any combination of functions or array of functions.
     * @returns returns self
     */
    use(...handlers: RequestHandlerType[]): Server;

    /**
     * Gives you hooks to run _before_ any routes are located.  This gives you
     * a chance to intercept the request and change headers, etc., that routing
     * depends on.  Note that req.params will _not_ be set yet.
     * @returns returns self
     */
    pre(...pre: RequestHandlerType[]): Server;

    /**
     * toString() the server for easy reading/output.
     */
    toString(): string;

    /**
     * Return debug information about the server.
     */
    getDebugInfo(): any;

    /** Name of the server. */
    name: string;

    /** Default version(s) to use in all routes. */
    versions: string[];

    /** bunyan instance. */
    log: Logger;

    /** List of content-types this server can respond with. */
    acceptable: string[];

    /** Once listen() is called, this will be filled in with where the server is running. */
    url: string;

    /** Node server instance */
    server: http.Server | https.Server | spdy.Server;

    /** Router instance */
    router: Router;

    /** Handle uncaught exceptions */
    handleUncaughtExceptions: boolean;

    /** enable DTrace support */
    dtrace: boolean;

    /** Custom response formatters */
    formatters: Formatters;

    /** Prevents calling next multiple times */
    onceNext: boolean;

    /** Throws error when next() is called more than once, enabled onceNext option */
    strictNext: boolean;

    /** Pre handlers */
    preChain: Chain;

    useChain: Chain;

    spdy?: boolean | undefined;

    http2?: boolean | undefined;

    ca: ServerOptions['ca'];

    certificate: ServerOptions['certificate'];

    key: ServerOptions['key'];

    passphrase: ServerOptions['passphrase'] | null;

    secure?: boolean | undefined;
}

export interface ChainOptions {
    onceNext?: boolean | undefined;

    strictNext?: boolean | undefined;
}

export interface Chain {
    /** Get handlers of a chain instance */
    getHandlers(): RequestHandler[];

    /** Utilize the given middleware `handler` */
    add(handler: RequestHandler): void;

    /** Returns the number of handlers */
    count(): number;

    /** Handle server requests, punting them down the middleware stack. */
    run(req: Request, res: Response, done: () => any): void;

    /** Prevents calling next multiple times */
    onceNext: boolean;

    /** Throws error when next() is called more than once, enables onceNext option */
    strictNext: boolean;
}

export interface RouterRegistryRadix {
    /**
     * Adds a route.
     */
    add(route: Route): boolean;

    /**
     * Removes a route.
     */
    remove(name: string): Route | undefined;

    /**
     * Registry for route.
     */
    lookup(method: string, pathname: string): Chain | undefined;

    /**
     * Get registry.
     */
    get(): Route[];

    /**
     * toString() serialization.
     */
    toString(): string;
}

export interface RouterOptions {
    log?: Logger | undefined;

    onceNext?: boolean | undefined;

    strictNext?: boolean | undefined;

    ignoreTrailingSlash?: boolean | undefined;

    registry?: RouterRegistryRadix | undefined;
}

export class Router {
    constructor(options: RouterOptions);

    /**
     * Lookup for route
     */
    lookup(req: Request, res: Response): Chain | undefined;

    /**
     * Lookup by name
     */
    lookupByName(name: string, req: Request, res: Response): Chain | undefined;

    /**
     * adds a route.
     * @param    options an options object
     * @returns  returns the route name if creation is successful.
     */
    mount(options: MountOptions, ...handlers: RequestHandlerType[]): string;

    /**
     * unmounts a route.
     * @param    name the route name
     * @returns       the name of the deleted route.
     */
    unmount(name: string): string;

    /**
     * Return mounted routes.
     */
    getRoutes(): Route[];

    /**
     * Default route, when no route found
     */
    defaultRoute(req: Request, res: Response, next: Next): void;

    /**
     * takes an object of route params and query params, and 'renders' a URL.
     * @param    routeName the route name
     * @param    params    an object of route params
     * @param    query     an object of query params
     */
    render(routeName: string, params: object, query?: object): string;

    /**
     * toString() serialization.
     */
    toString(): string;

    /**
     * Return information about the routes registered in the router.
     * @returns The routes in the router.
     */
    getDebugInfo(): any;

    name: string;

    log?: Logger | undefined;

    onceNext: boolean;

    strictNext: boolean;
}

export interface RequestAuthorization {
    scheme: string;
    credentials: string;
    basic?: {
        username: string;
        password: string;
    } | undefined;
}

export interface Request extends http.IncomingMessage {
    /**
     * Builds an absolute URI for the request.
     */
    absoluteUri(path: string): string;

    /**
     * checks if the accept header is present and has the value requested.
     * e.g., req.accepts('html');
     * @param    types an array of accept type headers
     */
    accepts(types: string | string[]): boolean;

    /**
     * checks if the request accepts the encoding types.
     * @param    types an array of accept type headers
     */
    acceptsEncoding(types: string | string[]): boolean;

    /**
     * gets the content-length header off the request.
     */
    getContentLength(): number;

    /**
     * pass through to getContentLength.
     */
    contentLength(): number;

    /**
     * gets the content-type header.
     */
    getContentType(): string;

    /**
     * pass through to getContentType.
     */
    contentType(): string;

    /**
     * retrieves the complete URI requested by the client.
     */
    getHref(): string;

    /**
     * pass through to getHref.
     */
    href(): string;

    /**
     * retrieves the request uuid. was created when the request was setup.
     */
    getId(): string;

    /**
     * pass through to getId.
     */
    id(): string;

    /**
     * retrieves the cleaned up url path.
     * e.g., /foo?a=1  =>  /foo
     */
    getPath(): string;

    /**
     * pass through to getPath.
     */
    path(): string;

    /**
     * returns the raw query string
     */
    getQuery(): string;

    // /**
    //  * pass through to getQuery.
    //  * @public
    //  * @function query
    //  * @returns {String}
    //  */
    // query(): string;

    /**
     * returns ms since epoch when request was setup.
     */
    time(): number;

    /**
     * returns a parsed URL object.
     */
    getUrl(): url.Url;

    /**
     * returns the accept-version header.
     */
    getVersion(): string;

    /**
     * pass through to getVersion.
     */
    version(): string;

    /**
     * returns the version of the route that matched.
     */
    matchedVersion(): string;

    /**
     * Get the case-insensitive request header key,
     * and optionally provide a default value (express-compliant).
     * Returns any header off the request. also, 'correct' any
     * correctly spelled 'referrer' header to the actual spelling used.
     * @param key - the key of the header
     * @param defaultValue - default value if header isn't found on the req
     */
    header(key: string, defaultValue?: string): string;

    /**
     * returns any trailer header off the request. also, 'correct' any
     * correctly spelled 'referrer' header to the actual spelling used.
     * @param    name  the name of the header
     * @param    defaultValue default value if header isn't found on the req
     */
    trailer(name: string, defaultValue?: string): string;

    /**
     * Check if the incoming request contains the Content-Type header field, and
     * if it contains the given mime type.
     * @param    type  a content-type header value
     */
    is(type: string): boolean;

    /**
     * Check if the incoming request is chunked.
     */
    isChunked(): boolean;

    /**
     * Check if the incoming request is kept alive.
     */
    isKeepAlive(): boolean;

    /**
     * Check if the incoming request is encrypted.
     */
    isSecure(): boolean;

    /**
     * Check if the incoming request has been upgraded.
     */
    isUpgradeRequest(): boolean;

    /**
     * Check if the incoming request is an upload verb.
     */
    isUpload(): boolean;

    /**
     * toString serialization
     */
    toString(): string;

    /**
     * retrieves the user-agent header.
     */
    userAgent(): string;

    /**
     * Start the timer for a request handler function. You must explicitly invoke
     * endHandlerTimer() after invoking this function. Otherwise timing information
     * will be inaccurate.
     * @param       handlerName The name of the handler.
     */
    startHandlerTimer(handlerName: string): void;

    /**
     * Stop the timer for a request handler function.
     * @param       handlerName The name of the handler.
     */
    endHandlerTimer(handlerName: string): void;

    /**
     * returns the connection state of the request. current valid values are
     * 'close' and 'aborted'.
     */
    connectionState(): string;

    /**
     * returns the route object to which the current request was matched to.
     * Route info object structure:
     * {
     *  path: '/ping/:name',
     *  method: 'GET',
     *  versions: [],
     *  name: 'getpingname'
     * }
     */
    getRoute(): Route;

    /** bunyan logger you can piggyback on. */
    log: Logger;

    /** available when queryParser plugin is used. */
    query?: any;

    /** available when bodyParser plugin is used. */
    body?: any;

    /** available when queryParser or bodyParser plugin is used with mapParams enabled. */
    params?: any;

    /** available when multipartBodyParser plugin is used. */
    files?: { [name: string]: File | undefined; } | undefined;

    /** available when authorizationParser plugin is used */
    username?: string | undefined;

    /** available when authorizationParser plugin is used */
    authorization?: RequestAuthorization | undefined;
}

export interface CacheOptions {
    maxAge: number;
}

export interface Response extends http.ServerResponse {
    /**
     * sets the cache-control header. `type` defaults to _public_,
     * and options currently only takes maxAge.
     * @param    type    value of the header
     * @param    [options] an options object
     * @returns          the value set to the header
     */
    cache(type: string, options?: CacheOptions): string;

    /**
     * sets the cache-control header. `type` defaults to _public_,
     * and options currently only takes maxAge.
     * @param    [options] an options object
     * @returns          the value set to the header
     */
    cache(options?: CacheOptions): string;

    /**
     * turns off all cache related headers.
     * @returns  self, the response object
     */
    noCache(): Response;

    /**
     * Appends the provided character set to the response's Content-Type.
     * e.g., res.charSet('utf-8');
     * @param    type char-set value
     * @returns  self, the response object
     */
    charSet(type: string): Response;

    /**
     * retrieves a header off the response.
     * @param    name the header name
     */
    get(name: string): string;

    /**
     * retrieves all headers off the response.
     */
    getHeaders(): any;

    /**
     * pass through to getHeaders.
     */
    headers(): any;

    /**
     * sets headers on the response.
     * @param    key  the name of the header
     * @param    value the value of the header
     */
    header(key: string, value?: any): any;

    /**
     * short hand method for:
     *     res.contentType = 'json';
     *     res.send({hello: 'world'});
     * @param    code    http status code
     * @param    body    value to json.stringify
     * @param    [headers] headers to set on the response
     */
    json(code: number, body: any, headers?: { [header: string]: string }): any;

    /**
     * short hand method for:
     *     res.contentType = 'json';
     *     res.send({hello: 'world'});
     * @param    body    value to json.stringify
     * @param    [headers] headers to set on the response
     */
    json(body: any, headers?: { [header: string]: string }): any;

    /**
     * sets the link heaader.
     * @param    key   the link key
     * @param    value the link value
     * @returns      the header value set to res
     */
    link(key: string, value: string): string;

    /**
     * sends the response object. pass through to internal __send that uses a
     * formatter based on the content-type header.
     * @param    [code] http status code
     * @param    [body] the content to send
     * @param    [headers]  any add'l headers to set
     * @returns  the response object
     */
    send(code?: number, body?: any, headers?: { [header: string]: string }): any;

    /**
     * sends the response object. pass through to internal __send that uses a
     * formatter based on the content-type header.
     * @param    [body] the content to send
     * @param    [headers]  any add'l headers to set
     * @returns  the response object
     */
    send(body?: any, headers?: { [header: string]: string }): any;

    /**
     * sends the response object. pass through to internal __send that skips
     * formatters entirely and sends the content as is.
     * @param    [code] http status code
     * @param    [body] the content to send
     * @param    [headers]  any add'l headers to set
     * @returns  the response object
     */
    sendRaw(code?: number, body?: any, headers?: { [header: string]: string }): any;

    /**
     * sends the response object. pass through to internal __send that skips
     * formatters entirely and sends the content as is.
     * @param    [body] the content to send
     * @param    [headers]  any add'l headers to set
     * @returns  the response object
     */
    sendRaw(body?: any, headers?: { [header: string]: string }): any;

    /**
     * sets a header on the response.
     * @param    name name of the header
     * @param    val  value of the header
     * @returns       self, the response object
     */
    set(name: string, val: string): Response;

    /**
     * sets a header on the response.
     * @param    val  object of headers
     * @returns       self, the response object
     */
    set(headers?: { [header: string]: string }): Response;

    /**
     * sets the http status code on the response.
     * @param    code http status code
     * @returns      the status code passed in
     */
    status(code: number): number;

    /**
     * toString() serialization.
     */
    toString(): string;

    /**
     * redirect is sugar method for redirecting.
     * res.redirect(301, 'www.foo.com', next);
     * `next` is mandatory, to complete the response and trigger audit logger.
     * @param    code the status code
     * @param    url to redirect to
     * @param    next - mandatory, to complete the response and trigger audit logger
     * @emits    redirect
     */
    redirect(code: number, url: string, next: Next): void;

    /**
     * redirect is sugar method for redirecting.
     * res.redirect({...}, next);
     * `next` is mandatory, to complete the response and trigger audit logger.
     * @param    url to redirect to or options object to configure a redirect or
     * @param    next - mandatory, to complete the response and trigger audit logger
     * @emits    redirect
     */
    redirect(opts: string | RedirectOptions, next: Next): void;

    /** HTTP status code. */
    code: number;

    /** short hand for the header content-length. */
    contentLength: number;

    /** short hand for the header content-type. */
    contentType: string;

    /** A unique request id (x-request-id). */
    id: string;
}

export interface RedirectOptions {
    /**
     * whether to redirect to http or https
     */
    secure?: boolean | undefined;

    /**
     * redirect location's hostname
     */
    hostname?: string | undefined;

    /**
     * redirect location's pathname
     */
    pathname?: string | undefined;

    /**
     * redirect location's port number
     */
    port?: string | undefined;

    /**
     * redirect location's query string parameters
     */
    query?: string|object | undefined;

    /**
     * if true, `options.query`
     * stomps over any existing query
     * parameters on current URL.
     * by default, will merge the two.
     */
    overrideQuery?: boolean | undefined;

    /**
     * if true, sets 301. defaults to 302.
     */
    permanent?: boolean | undefined;
}

export interface Next {
    (err?: any): void;
}

export interface RouteSpec {
    method: string;
    name?: string | undefined;
    path: string | RegExp;
    versions?: string[] | undefined;
}

export interface Route {
    name: string;
    method: string;
    path: string | RegExp;
    spec: RouteSpec;
    chain: Chain;
}

export interface RouteOptions {
    name?: string | undefined;

    path?: string | RegExp | undefined;

    url?: string | RegExp | undefined;

    urlParamPattern?: RegExp | undefined;

    contentType?: string | string[] | undefined;

    version?: string | undefined;

    versions?: string[] | undefined;
}

export interface MountOptions {
    name: string;

    method: string;

    path?: string | RegExp | undefined;

    url?: string | RegExp | undefined;

    urlParamPattern?: RegExp | undefined;

    contentType?: string | string[] | undefined;

    version?: string | undefined;

    versions?: string[] | undefined;
}

export type FindRouteCallback = (err: Error, route?: Route, params?: any) => void;

export type RequestHandler = (req: Request, res: Response, next: Next) => any;
export type RequestHandlerType = RequestHandler | RequestHandler[];

export interface ServerUpgradeResponse {
    /**
     * Set the status code of the response.
     * @param code - the http status code
     */
    status(code: number): number;

    /**
     * Sends the response.
     * @param code - the http status code
     * @param body - the response to send out
     */
    send(code: number, body: any): any;

    /**
     * Sends the response.
     * @param body - the response to send out
     */
    send(body: any): boolean;

    /**
     * Ends the response
     */
    end(): boolean;

    /**
     * Write to the response.
     */
    write(): boolean;

    /**
     * Write to the head of the response.
     * @param statusCode - the http status code
     * @param reason -  a message
     */
    writeHead(statusCode: number, reason?: string): void;

    /**
     * Attempt to upgrade.
     */
    claimUpgrade(): any;
}

export namespace bunyan {
    interface RequestCaptureOptions {
        /** The stream to which to write when dumping captured records. */
        stream?: Logger.Stream | undefined;

        /** The streams to which to write when dumping captured records. */
        streams?: ReadonlyArray<Logger.Stream> | undefined;

        /**
         * The level at which to trigger dumping captured records. Defaults to
         * bunyan.WARN.
         */
        level?: Logger.LogLevel | undefined;

        /** Number of records to capture. Default 100. */
        maxRecords?: number | undefined;

        /**
         * Number of simultaneous request id capturing buckets to maintain.
         * Default 1000.
         */
        maxRequestIds?: number | undefined;

        /**
         * If true, then dump captured records on the *default* request id when
         * dumping. I.e. dump records logged without "req_id" field. Default
         * false.
         */
        dumpDefault?: boolean | undefined;
    }

    /**
     * A Bunyan stream to capture records in a ring buffer and only pass through
     * on a higher-level record. E.g. buffer up all records but only dump when
     * getting a WARN or above.
     */
    class RequestCaptureStream extends stream.Stream {
        constructor(opts: RequestCaptureOptions);

        /** write to the stream */
        write(record: any): void;
    }

    const serializers: Logger.Serializers & {
        err: Logger.Serializer,
        req: Logger.Serializer,
        res: Logger.Serializer,
        client_req: Logger.Serializer,
        client_res: Logger.Serializer
    };

    /** create a bunyan logger */
    function createLogger(name: string): Logger;
}

export function createServer(options?: ServerOptions): Server;

export type Formatter = (req: Request, res: Response, body: any) => string | Buffer | null;

export interface Formatters {
    [contentType: string]: Formatter;
}

export const formatters: Formatters;

export namespace plugins {
  namespace pre {
    /**
     * Provide req.set(key, val) and req.get(key) methods for setting and retrieving context to a specific request.
     */
    function context(): RequestHandler;

    function dedupeSlashes(): RequestHandler;

    /**
     * This pre handler fixes issues with node hanging when an asyncHandler is used prior to bodyParser.
     */
    function pause(): RequestHandler;

    /**
     * Cleans up duplicate or trailing / on the URL
     */
    function sanitizePath(): RequestHandler;

    /**
     * Automatically reuse incoming request header as the request id.
     */
    function reqIdHeaders(options: { headers: string[] }): RequestHandler;

    /**
     * Checks req.urls query params with strict key/val format and rejects non-strict requests with status code 400.
     */
    function strictQueryParams(options?: { message: string }): RequestHandler;

    /**
     * Regexp to capture curl user-agents
     */
    function userAgentConnection(options?: {
      userAgentRegExp: any;
    }): RequestHandler;
  }

  // *************** This module includes the following header parser plugins:

  /**
   * Check the client's Accept header can be handled by this server.
   */
  function acceptParser(accepts: string[]): RequestHandler;

  type AuditLoggerContext = (
    req: Request,
    res: Response,
    route: any,
    error: any,
  ) => any;

  interface AuditLoggerOptions {
    /**
     * Bunyan logger
     */
    log: Logger;

    /**
     * The event from the server which initiates the
     * log, one of 'pre', 'routed', or 'after'
     */
    event: 'pre' | 'routed' | 'after';

    /**
     * Restify server. If passed in, causes server to emit 'auditlog' event after audit logs are flushed
     */
    server?: Server | undefined;

    /**
     * The optional context function of signature
     * f(req, res, route, err).  Invoked each time an audit log is generated. This
     * function can return an object that customizes the format of anything off the
     * req, res, route, and err objects. The output of this function will be
     * available on the `context` key in the audit object.
     */
    context?: AuditLoggerContext | undefined;

    /**
     * Ringbuffer which is written to if passed in
     */
    logBuffer?: any;

    /**
     * When true, prints audit logs. default true.
     */
    printLog?: boolean | undefined;

    body?: boolean | undefined;
  }

  /**
   * An audit logger for recording all handled requests
   */
  function auditLogger(options: AuditLoggerOptions): (...args: any[]) => void;

  /**
   * Authorization header
   */
  function authorizationParser(options?: any): RequestHandler;

  interface HandlerCandidate {
    handler: RequestHandler | RequestHandler[];
    version?: string | string[] | undefined;
    contentType?: string | string[] | undefined;
  }

  /**
   * Runs first handler that matches to the condition
   */
  function conditionalHandler(
    candidates: HandlerCandidate | HandlerCandidate[],
  ): RequestHandler;

  /**
   * Conditional headers (If-*)
   */
  function conditionalRequest(): RequestHandler[];

  interface CpuUsageThrottleOptions {
    limit?: number | undefined;
    max?: number | undefined;
    interval?: number | undefined;
    halfLife?: number | undefined;
  }

  /**
   * Cpu Throttle middleware
   */
  function cpuUsageThrottle(opts?: CpuUsageThrottleOptions): RequestHandler;

  /**
   * Handles disappeared CORS headers
   */
  function fullResponse(): RequestHandler;

  // ************ This module includes the following data parsing plugins:

  interface BodyParserOptions {
    /**
     * The maximum size in bytes allowed in the HTTP body. Useful for limiting clients from hogging server memory.
     */
    maxBodySize?: number | undefined;

    /**
     * If req.params should be filled with parsed parameters from HTTP body.
     */
    mapParams?: boolean | undefined;

    /**
     * If req.params should be filled with the contents of files sent through a multipart request.
     * Formidable is used internally for parsing, and a file is denoted as a multipart part with the filename option set in its Content-Disposition.
     * This will only be performed if mapParams is true.
     */
    mapFiles?: boolean | undefined;

    /**
     * If an entry in req.params should be overwritten by the value in the body if the names are the same.
     * For instance, if you have the route /:someval, and someone posts an x-www-form-urlencoded Content-Type with the body someval=happy to /sad,
     * the value will be happy if overrideParams is true, sad otherwise.
     */
    overrideParams?: boolean | undefined;

    /**
     * A callback to handle any multipart part which is not a file.
     * If this is omitted, the default handler is invoked which may or may not map the parts into req.params, depending on the mapParams-option.
     */
    multipartHandler?(): void;

    /**
     * A callback to handle any multipart file.
     * It will be a file if the part have a Content-Disposition with the filename parameter set.
     * This typically happens when a browser sends a form and there is a parameter similar to <input type="file" />.
     * If this is not provided, the default behaviour is to map the contents into req.params.
     */
    multipartFileHandler?(): void;

    /**
     * If you want the uploaded files to include the extensions of the original files (multipart uploads only). Does nothing if multipartFileHandler is defined.
     */
    keepExtensions?: boolean | undefined;

    /**
     * Where uploaded files are intermediately stored during transfer before the contents is mapped into req.params. Does nothing if multipartFileHandler is defined.
     */
    uploadDir?: string | undefined;

    /**
     * If you want to support html5 multiple attribute in upload fields.
     */
    multiples?: boolean | undefined;

    /**
     * If you want checksums calculated for incoming files, set this to either sha1 or md5.
     */
    hash?: string | undefined;

    /**
     * Set to true if you want to end the request with a UnsupportedMediaTypeError when none of the supported content types was given.
     */
    rejectUnknown?: boolean | undefined;

    requestBodyOnGet?: boolean | undefined;

    reviver?: any;

    maxFieldsSize?: number | undefined;

    maxFileSize?: number | undefined;
  }

  /**
   * Parses POST bodies to req.body. automatically uses one of the following parsers based on content type.
   */
  function bodyParser(options?: BodyParserOptions): RequestHandler[];

  /**
   * Reads the body of the request.
   */
  function bodyReader(options?: { maxBodySize?: number | undefined }): RequestHandler;

  interface UrlEncodedBodyParserOptions {
    mapParams?: boolean | undefined;
    overrideParams?: boolean | undefined;
    bodyReader?: boolean | undefined;
  }

  /**
   * Parse the HTTP request body IFF the contentType is application/x-www-form-urlencoded.
   *
   * If req.params already contains a given key, that key is skipped and an
   * error is logged.
   */
  function urlEncodedBodyParser(
    options?: UrlEncodedBodyParserOptions,
  ): RequestHandler[];

  interface JsonBodyParserOptions {
    mapParams?: boolean | undefined;
    overrideParams?: boolean | undefined;
    reviver?(key: any, value: any): any;
    bodyReader?: boolean | undefined;
  }

  /**
   * Parses JSON POST bodies
   */
  function jsonBodyParser(options?: JsonBodyParserOptions): RequestHandler[];

  /**
   * Parses JSONP callback
   */
  function jsonp(): RequestHandler;

  interface MultipartBodyParser {
    overrideParams?: boolean | undefined;
    multiples?: boolean | undefined;
    keepExtensions?: boolean | undefined;
    uploadDir?: string | undefined;
    maxFieldsSize?: number | undefined;
    hash?: string | undefined;
    multipartFileHandler?: any;
    multipartHandler?: any;
    mapParams?: boolean | undefined;
    mapFiles?: boolean | undefined;
    maxFileSize?: number | undefined;
  }

  /**
   * Parses JSONP callback
   */
  function multipartBodyParser(options?: MultipartBodyParser): RequestHandler;

  interface QueryParserOptions {
    /**
     * Default `false`. Copies parsed query parameters into `req.params`.
     */
    mapParams?: boolean | undefined;

    /**
     * Default `false`. Only applies when if mapParams true. When true, will stomp on req.params field when existing value is found.
     */
    overrideParams?: boolean | undefined;

    /**
     *  Default false. Transform `?foo.bar=baz` to a nested object: `{foo: {bar: 'baz'}}`.
     */
    allowDots?: boolean | undefined;

    /**
     * Default 20. Only transform `?a[$index]=b` to an array if `$index` is less than `arrayLimit`.
     */
    arrayLimit?: number | undefined;

    /**
     * Default 5. The depth limit for parsing nested objects, e.g. `?a[b][c][d][e][f][g][h][i]=j`.
     */
    depth?: number | undefined;

    /**
     * Default 1000. Maximum number of query params parsed. Additional params are silently dropped.
     */
    parameterLimit?: number | undefined;

    /**
     * Default true. Whether to parse `?a[]=b&a[1]=c` to an array, e.g. `{a: ['b', 'c']}`.
     */
    parseArrays?: boolean | undefined;

    /**
     * Default false. Whether `req.query` is a "plain" object -- does not inherit from `Object`.
     * This can be used to allow query params whose names collide with Object methods, e.g. `?hasOwnProperty=blah`.
     */
    plainObjects?: boolean | undefined;

    /**
     * Default false. If true, `?a&b=` results in `{a: null, b: ''}`. Otherwise, `{a: '', b: ''}`.
     */
    strictNullHandling?: boolean | undefined;
  }

  /**
   * Parses URL query parameters into `req.query`. Many options correspond directly to option defined for the underlying [qs.parse](https://github.com/ljharb/qs)
   */
  function queryParser(options?: QueryParserOptions): RequestHandler;

  interface RequestLogger {
    properties?: any;
    serializers?: any;
    headers?: any;
    log?: any;
  }

  /**
   * Adds timers for each handler in your request chain
   *
   * `options.properties` properties to pass to bunyan's `log.child()` method
   */
  function requestLogger(options?: RequestLogger): RequestHandler;

  // ******************** The module includes the following response plugins:

  /**
   * expires requests based on current time + delta
   * @param delta - age in seconds
   */
  function dateParser(delta?: number): RequestHandler;

  /**
   * gzips the response if client send `accept-encoding: gzip`
   * @param options options to pass to gzlib
   */
  function gzipResponse(options?: zlib.ZlibOptions): RequestHandler;

  interface InflightRequestThrottleOptions {
    limit: number;
    server: Server;
    err: any;
  }

  function inflightRequestThrottle(
    opts: InflightRequestThrottleOptions,
  ): RequestHandler;

  interface ServeStatic {
    appendRequestPath?: boolean | undefined;
    directory?: string | undefined;
    maxAge?: number | undefined;
    match?: any;
    charSet?: string | undefined;
    file?: string | undefined;
    etag?: string | undefined;
    default?: any;
    gzip?: boolean | undefined;
  }

  /**
   * Used to serve static files
   */
  function serveStatic(options?: ServeStatic): RequestHandler;

  interface ServeStaticFiles {
    maxAge?: number | undefined;
    etag?: string | undefined;
    setHeaders?: ((res: Response, path: string, stat: any) => any) | undefined;
  }

  /**
   * Used to serve static files from a given directory
   */
  function serveStaticFiles(
    dir: string,
    options?: ServeStaticFiles,
  ): RequestHandler;

  interface ThrottleOptions {
    burst?: number | undefined;
    rate?: number | undefined;
    setHeaders?: boolean | undefined;
    ip?: boolean | undefined;
    username?: boolean | undefined;
    xff?: boolean | undefined;
    tokensTable?: any;
    maxKeys?: number | undefined;
    overrides?: any; // any
  }

  /**
   *  throttles responses
   */
  function throttle(options?: ThrottleOptions): RequestHandler;

  type MetricsCallback = (
    /**
     *  An error if the request had an error
     */
    err: Error,

    /**
     *  Object that contains the various metrics that are returned
     */
    metrics: MetricsCallbackOptions,

    /**
     * The request obj
     */
    req: Request,

    /**
     * The response obj
     */
    res: Response,

    /**
     * The route obj that serviced the request
     */
    route: Route,
  ) => void;

  type TMetricsCallback = 'close' | 'aborted' | undefined;

  interface MetricsCallbackOptions {
    /**
     * Status code of the response. Can be undefined in the case of an `uncaughtException`.
     * Otherwise, in most normal scenarios, even calling `res.send()` or `res.end()` should result in a 200 by default.
     */
    statusCode: number;

    /**
     * HTTP request verb
     */
    method: string;

    /**
     * latency includes both request is flushed and all handlers finished
     */
    totalLatency: number;

    /**
     * Request latency
     */
    latency: number;

    /**
     * pre handlers latency
     */
    preLatency: number | null;

    /**
     * use handlers latency
     */
    useLatency: number | null;

    /**
     * req.path() value
     */
    path: string;

    /**
     * Number of inflight requests pending in restify
     */
    inflightRequests: number;

    /**
     * Same as `inflightRequests`
     */
    unfinishedRequests: number;

    /**
     * If this value is set, err will be a corresponding `RequestCloseError` or `RequestAbortedError`.
     *
     * If connectionState is either 'close' or 'aborted', then the statusCode is not applicable since the connection was severed before a response was written.
     */
    connectionState: TMetricsCallback;
  }

  /**
   * Listens to the server's after event and emits information about that request (5.x compatible only).
   *
   * ```
   * server.on('after', plugins.metrics({ server }, (err, metrics, req, res, route) =>
   * {
   *    // metrics is an object containing information about the request
   * }));
   * ```
   */
  function metrics(
    opts: { server: Server },
    callback: MetricsCallback,
  ): (...args: any[]) => void;

  /**
   * Parse the client's request for an OAUTH2 access tokensTable
   *
   * Subsequent handlers will see `req.oauth2`, which looks like:
   * ```
   * {
   *    oauth2: {accessToken: 'mF_9.B5f-4.1JqM&p=q'}
   * }
   * ```
   */
  function oauth2TokenParser(): RequestHandler;

  interface RequestExpiryOptions {
    /**
     * Header name of the absolute time for request expiration
     */
    absoluteHeader?: string | undefined;

    /**
     * Header name for the start time of the request
     */
    startHeader?: string | undefined;

    /**
     * The header name for the time in milliseconds that should ellapse before the request is considered expired.
     */
    timeoutHeader?: string | undefined;
  }

  /**
   * A request expiry will use headers to tell if the incoming request has expired or not.
   *
   * There are two options for this plugin:
   *   1. Absolute Time
   *     * Time in Milliseconds since the Epoch when this request should be considered expired
   *   2. Timeout
   *     * The request start time is supplied
   *     * A timeout, in milliseconds, is given
   *     * The timeout is added to the request start time to arrive at the absolute time
   *       in which the request is considered expires
   */
  function requestExpiry(options?: RequestExpiryOptions): RequestHandler;
}

export namespace pre {
    /**
     * Provide req.set(key, val) and req.get(key) methods for setting and retrieving context to a specific request.
     */
    function context(): RequestHandler;

    function dedupeSlashes(): RequestHandler;

    /**
     * This pre handler fixes issues with node hanging when an asyncHandler is used prior to bodyParser.
     */
    function pause(): RequestHandler;

    /**
     * Cleans up duplicate or trailing / on the URL
     */
    function sanitizePath(): RequestHandler;

    /**
     * Automatically reuse incoming request header as the request id.
     */
    function reqIdHeaders(options: { headers: string[] }): RequestHandler;

    /**
     * Checks req.urls query params with strict key/val format and rejects non-strict requests with status code 400.
     */
    function strictQueryParams(options?: { message: string }): RequestHandler;

    /**
     * Regexp to capture curl user-agents
     */
    function userAgentConnection(options?: { userAgentRegExp: any }): RequestHandler;
}