@artlife/micro/build/index.d.ts

/// <reference types="node" />
import * as express from 'express';
import { asyncHandler, retry, sleep, verifyBodyParam, verifyQueryParam } from './utils';
export { asyncHandler, retry, sleep, verifyBodyParam, verifyQueryParam };
import * as http from 'http';
/**
 * Logging interface. Allows log from multiple microservices to be aggregated.
 */
export interface ILog {
    /**
     * Issue a warning.
     */
    warn(...args: any[]): void;
    /**
     * Issue an information message.
     */
    info(...args: any[]): void;
    /**
     * Issue a verbose message.
     */
    verbose(...args: any[]): void;
    /**
     * Record an error message.
     */
    error(...args: any[]): void;
    /**
     * Record an exception that was thrown
     */
    exception(err: any, ...args: any[]): void;
}
/**
 * Interface used to time various events.
 */
export interface ITimer {
    /**
     * Start a timer.
     *
     * @param timerName The name of the timer.
     */
    start(timerName: string): void;
    /**
     * Stop a timer.
     *
     * @param timerName The name of the timer.
     */
    stop(timerName: string): void;
}
/**
 * Interface for a service to output metrics.
 */
export interface IMetrics {
    /**
     * Output a discrete metric value.
     *
     * @param name The name of the metric.
     * @param value The value of the metric.
     */
    discrete(name: string, value: number): void;
    /**
     * Output a continous metric value.
     *
     * @param name The name of the metric.
     * @param value The value of the metric.
     */
    continuous(name: string, value: number): void;
}
/**
 * Configures a microservice.
 */
export interface IMicroServiceConfig {
    /**
     * Enable verbose logging from micro.
     */
    verbose?: boolean;
    /**
     * Host to run the REST API.
     */
    host?: string;
    /**
     * Port to run the REST API.
     */
    port?: number;
    /**
     * Defines the connection to the RabbitMQ server.
     */
    messagingHost?: string;
}
/**
 * Interface for responding to events.
 */
export interface IEventResponse {
    /**
     * Acknoledge that the event was successfully handled.
     */
    ack(): Promise<void>;
}
export interface IEventHandler {
}
/**
 * Defines a potentially asynchronous callback function for handling an incoming event.
 */
export declare type EventHandlerFn<EventArgsT> = (eventArgs: EventArgsT, response: IEventResponse) => Promise<void>;
/**
 * Defines a potentially asynchronous callback function for handling an incoming HTTP GET request.
 */
export declare type GetRequestHandlerFn = (request: express.Request, response: express.Response) => Promise<void>;
/**
 * Defines a potentially asynchronous callback function for handling an incoming HTTP POST request.
 */
export declare type PostRequestHandlerFn = (request: express.Request, response: express.Response) => Promise<void>;
/**
 * Interface for defining HTTP routes on a REST API.
 */
export interface IHttpServer {
    /**
     * Create a handler for incoming HTTP GET requests.
     * Implemented by Express under the hood.
     */
    get(route: string, requestHandler: GetRequestHandlerFn): void;
    /**
     * Create a handler for incoming HTTP POST requests.
     * Implemented by Express under the hood
     *
     * @param route
     * @param requestHandler
     */
    post(route: string, requestHandler: PostRequestHandlerFn): void;
    /**
     * Setup serving of static files.
     *
     * @param dirPath The path to the directory that contains static files.
     */
    static(dirPath: string): void;
}
/**
 * Interface for issuing HTTP requests to a REST API.
 */
export interface IHttpRequest {
    /**
     * Make a HTTP get request to another service.
     *
     * @param serviceName The name (logical or host) of the service.
     * @param route The HTTP route on the service to make the request to.
     * @param params Query parameters for the request.
     */
    get(serviceName: string, route: string, body?: any): Promise<any>;
    /**
     * Make a HTTP get request to another service.
     *
     * @param serviceName The name (logical or host) of the service.
     * @param route The HTTP route on the service to make the request to.
     * @param params Query parameters for the request.
     */
    post(serviceName: string, route: string, body: any): Promise<void>;
    /**
     * Forward HTTP get request to another named service.
     * The response from the forward requests is automatically piped into the passed in response.
     *
     * @param serviceName The name of the service to forward the request to.
     * @param route The HTTP GET route to forward to.
     * @param params Query parameters for the request.
     * @param res The stream to pipe response to.
     */
    forward(serviceName: string, route: string, req: express.Request, res: express.Response): void;
}
/**
 * Interface that represents a particular microservice instance.
 */
export interface IMicroService {
    /**
     * Returns true if the messaging system is currently available.
     */
    isMessagingAvailable(): boolean;
    /**
     * Create a handler for a named incoming event from a direct queue.
     * Implemented by Rabbitmq under the hood for reliable messaging.
     *
     * @param eventName The name of the event to handle.
     * @param eventHandler Callback to be invoke when the incoming event is received.
     */
    on<EventArgsT = any>(eventName: string, eventHandlerFn: EventHandlerFn<EventArgsT>): Promise<IEventHandler>;
    /**
     * Unregister a previously register event handler.
     *
     * @param eventHandler The event handler to unregister.
     */
    off(eventHandler: IEventHandler): void;
    /**
     * Create a once-off handler for a named incoming event.
     * The event handler will only be invoke once before the event is unregistered.
     * Implemented by Rabbitmq under the hood for reliable messaging.
     *
     * @param eventName The name of the event to handle.
     * @param eventHandler Callback to be invoke when the incoming event is received.
     */
    once<EventArgsT = any>(eventName: string, eventHandlerFn: EventHandlerFn<EventArgsT>): Promise<void>;
    /***
     * Wait for a single incoming event, returns the events arguments and then unregister the event handler.
     *
     * @param eventName The name of the event to handle.
     *
     * @returns A promise to resolve the incoming event's arguments.
     */
    waitForOneEvent<EventArgsT = any>(eventName: string): Promise<EventArgsT>;
    /**
     * Emit a named outgoing event.
     * Implemented by Rabbitmq under the hood for reliable messaging.
     *
     * @param eventName The name of the event to emit.
     * @param eventArgs Event args to publish with the event and be received at the other end.
     */
    emit<EventArgsT = any>(eventName: string, eventArgs: EventArgsT): Promise<void>;
    /**
     * Reference to the logging interface.
     * This allows the logging from multiple microservices to be aggregated.
     */
    readonly log: ILog;
    /**
     * Reference to the timer interface.
     * Allows a service to time code for performance.
     */
    readonly timer: ITimer;
    /**
     * Reference to the metrics interface.
     * Allows a service to output metrics.
     */
    readonly metrics: IMetrics;
    /**
     * Reference to the express object.
     */
    readonly expressApp: express.Express;
    /**
     * Reference to the HTTP server.
     */
    readonly httpServer: http.Server;
    /**
     * Interface for defining the REST API.
     */
    readonly rest: IHttpServer;
    /**
     * Interface for issuing HTTP requests to a REST API.
     */
    readonly request: IHttpRequest;
    /**
     * Starts the microservice.
     * It starts listening for incoming HTTP requests and events.
     */
    start(): Promise<void>;
}
/**
 * Instantiates a microservice.
 *
 * @param [config] Optional configuration for the microservice.
 */
export declare function micro(config?: IMicroServiceConfig): IMicroService;