/**
* 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 .
*/
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} The result, which indicates if authorization is valid or not.
*/
export declare type ApiAuthorizer = (req: express.Request) => boolean | Promise;
/**
* A Basic Auth authorizer.
*
* @param {string} user The username.
* @param {string} password The password.
*
* @return {boolean|Promise} The result, which indicates if authorization is valid or not.
*/
export declare type BasicAuthAuthorizer = (user: string, password: string) => boolean | Promise;
/**
* 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} The result, which indicates if authorization is valid or not.
*/
export declare type TokenAuthorizer = (token: string) => boolean | Promise;
/**
* 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} The promise, which indicates if operation successful or not.
*/
start(port?: number): Promise;
/**
* Stops the host.
*
* @return {Promise} The promise, which indicates if operation successful or not.
*/
stop(): Promise;
/**
* 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 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;
/**
* 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;
/**
* 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} The promise with the result of the action.
*/
withDatabase(action: (db: TDatabase) => (TResult | PromiseLike), opts?: TOptions): Promise;
}