@egodigital/egoose/lib/apis/host.d.ts

/**
 * This file is part of the @egodigital/egoose distribution.
 * Copyright (c) e.GO Digital GmbH, Aachen, Germany (https://www.e-go-digital.com/)
 *
 * @egodigital/egoose is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, version 3.
 *
 * @egodigital/egoose is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */
import * as bodyParser from 'body-parser';
import * as errorHandler from 'errorhandler';
import { MongoDatabase, MongoDatabaseOptions } from '../mongo/index';
import { Logger, LogType } from '../diagnostics/logger';
import * as express from 'express';
/**
 * An API authorizer.
 *
 * @param {express.Request} req The current request context.
 *
 * @return {boolean|Promise<boolean>} The result, which indicates if authorization is valid or not.
 */
export declare type ApiAuthorizer = (req: express.Request) => boolean | Promise<boolean>;
/**
 * A Basic Auth authorizer.
 *
 * @param {string} user The username.
 * @param {string} password The password.
 *
 * @return {boolean|Promise<boolean>} The result, which indicates if authorization is valid or not.
 */
export declare type BasicAuthAuthorizer = (user: string, password: string) => boolean | Promise<boolean>;
/**
 * Body parser options.
 */
export declare type BodyParserOptions = bodyParser.OptionsJson & bodyParser.OptionsText & bodyParser.OptionsUrlencoded;
/**
 * Options for an 'initialize' method of an 'ApiHost' object.
 */
export interface InitializeApiHostOptions {
    /**
     * Is invoked after an Express app instance has been created.
     */
    onAppCreated?: (app: express.Express) => void;
}
/**
 * A token based authorizer.
 *
 * @param {string} token The token to check.
 *
 * @return {boolean|Promise<boolean>} The result, which indicates if authorization is valid or not.
 */
export declare type TokenAuthorizer = (token: string) => boolean | Promise<boolean>;
/**
 * Value for (or from) 'useBodyParser()' method of an ApiHost instance.
 */
export declare type UseBodyParserSetting = boolean | BodyParserOptions;
/**
 * Value for (or from) 'useBodyParser()' method of an ApiHost instance.
 */
export declare type UseErrorHandlerSetting = boolean | errorHandler.Options;
/**
 * An API host.
 */
export declare class ApiHost {
    private _app;
    private _authorizer;
    private _logger;
    private _poweredBy;
    private _root;
    private _server;
    private _useBodyParser;
    private _useErrorHandler;
    /**
     * Gets the underlying Express app instance.
     */
    readonly app: express.Express;
    /**
     * Gets or sets if an authorizer should be used or not.
     *
     * @param {ApiAuthorizer} [newValue] The new value.
     *
     * @return {ApiAuthorizer|this} The current value or that instance if new value has been set.
     */
    authorizer(): ApiAuthorizer;
    authorizer(newValue: ApiAuthorizer): this;
    /**
     * (Re-)Initializes the host.
     *
     * @param {InitializeApiHostOptions} [opts] Custom options.
     */
    initialize(opts?: InitializeApiHostOptions): void;
    /**
     * Gets if the host is currently running or not.
     */
    readonly isRunning: boolean;
    /**
     * Gets the underlying logger.
     */
    readonly logger: Logger;
    /**
     * Gets or sets the 'X-Powered-By' header.
     *
     * @param {string} [newValue] The new value.
     *
     * @return {string|this} The current value or that instance if new value has been set.
     */
    poweredBy(): string;
    poweredBy(newValue: string): this;
    /**
     * Gets the root endpoint.
     */
    readonly root: express.Router;
    /**
     * Sets a 'Basic Auth' based authorizer.
     *
     * @param {BasicAuthAuthorizer} authorizer The authorizer.
     *
     * @return this
     */
    setBasicAuth(authorizer: BasicAuthAuthorizer): this;
    /**
     * Sets a prefixed based authorizer.
     *
     * @param {TokenAuthorizer} authorizer The authorizer.
     * @param {string} [prefix] The prefix.
     *
     * @return this
     */
    setPrefixedAuthorizer(authorizer: TokenAuthorizer, prefix?: string): this;
    /**
     * Sets up a new api / app instance.
     *
     * @param {express.Express} newApp The instance to setup.
     * @param {express.Router} newRoot The API root.
     */
    protected setupApi(newApp: express.Express, newRoot: express.Router): void;
    /**
     * Sets up a new logger instance.
     *
     * @param {Logger} newLogger The instance to setup.
     */
    protected setupLogger(newLogger: Logger): void;
    /**
     * Starts the host.
     *
     * @param {number} [port] The custom port to use. By default 'APP_PORT' environment variable is used.
     *                        Otherwise 80 is the default port.
     *
     * @return {Promise<boolean>} The promise, which indicates if operation successful or not.
     */
    start(port?: number): Promise<boolean>;
    /**
     * Stops the host.
     *
     * @return {Promise<boolean>} The promise, which indicates if operation successful or not.
     */
    stop(): Promise<boolean>;
    /**
     * Gets or sets if 'body-parser' module should be used or not.
     *
     * @param {UseBodyParserSetting} [newValue] The new value.
     *
     * @return {UseBodyParserSetting|this} The current value or that instance if new value has been set.
     */
    useBodyParser(): UseBodyParserSetting;
    useBodyParser(newValue: UseBodyParserSetting): this;
    /**
     * Gets or sets if 'errorhandler' module should be used or not.
     *
     * @param {UseErrorHandlerSetting} [newValue] The new value.
     *
     * @return {UseErrorHandlerSetting|this} The current value or that instance if new value has been set.
     */
    useErrorHandler(): UseErrorHandlerSetting;
    useErrorHandler(newValue: UseErrorHandlerSetting): this;
}
/**
 * An API with MongoDB helper methods.
 */
export declare class MongoApiHost<TDatabase extends MongoDatabase = MongoDatabase, TOptions extends MongoDatabaseOptions = MongoDatabaseOptions> extends ApiHost {
    /**
     * Returns the database class.
     *
     * @return {MongoDatabase} The class.
     */
    protected getDatabaseClass(): typeof MongoDatabase;
    /**
     * Log something into the database.
     * This requires a 'logs' collection, described by 'LogsDocument' interface.
     *
     * @param {any} message The message.
     * @param {LogType} type The type.
     * @param {any} [payload] The (optional) payload.
     */
    log(message: any, type: LogType, payload?: any): Promise<void>;
    /**
     * Options a new connection to a database.
     *
     * @param {TOptions} [opts] The custom options to use.
     *
     * @return {TDatabase} The new, opened, database.
     */
    openDatabase(opts?: TOptions): Promise<TDatabase>;
    /**
     * Opens a data connection and invokes an action for it.
     * After invokation, the database is closed automatically.
     *
     * @param {Function} action The action to invoke.
     * @param {TOptions} [opts] Custom database options.
     *
     * @return {Promise<TResult>} The promise with the result of the action.
     */
    withDatabase<TResult = any>(action: (db: TDatabase) => (TResult | PromiseLike<TResult>), opts?: TOptions): Promise<TResult>;
}