@nmshd/typescript-rest 3.0.5

package/src/server/server.ts

@@ -0,0 +1,340 @@
+'use strict';
+
+import * as debug from 'debug';
+import * as express from 'express';
+import * as fs from 'fs-extra';
+import * as _ from 'lodash';
+import 'multer';
+import * as path from 'path';
+import * as YAML from 'yamljs';
+import { FileLimits, HttpMethod, ParameterConverter, ServiceAuthenticator, ServiceFactory } from './model/server-types';
+import { ServerContainer } from './server-container';
+
+const serverDebugger = debug('typescript-rest:server:build');
+
+/**
+ * The Http server main class.
+ */
+export class Server {
+    /**
+     * Create the routes for all classes decorated with our decorators
+     */
+    public static buildServices(router: express.Router, ...types: Array<any>) {
+        if (!Server.locked) {
+            serverDebugger('Creating typescript-rest services handlers');
+            const serverContainer = ServerContainer.get();
+            serverContainer.router = router;
+            serverContainer.buildServices(types);
+        }
+    }
+
+    /**
+     * An alias for Server.loadServices()
+     */
+    public static loadControllers(router: express.Router, patterns: string | Array<string>, baseDir?: string) {
+        Server.loadServices(router, patterns, baseDir);
+    }
+
+    /**
+     * Load all services from the files that matches the patterns provided
+     */
+    public static loadServices(router: express.Router, patterns: string | Array<string>, baseDir?: string) {
+        if (!Server.locked) {
+            serverDebugger('Loading typescript-rest services %j. BaseDir: %s', patterns, baseDir);
+            const importedTypes: Array<Function> = [];
+            const requireGlob = require('require-glob');
+            baseDir = baseDir || process.cwd();
+            const loadedModules: Array<any> = requireGlob.sync(patterns, {
+                cwd: baseDir
+            });
+
+            _.values(loadedModules).forEach((serviceModule) => {
+                _.values(serviceModule)
+                    .filter((service: Function) => typeof service === 'function')
+                    .forEach((service: Function) => {
+                        importedTypes.push(service);
+                    });
+            });
+
+            try {
+                Server.buildServices(router, ...importedTypes);
+            } catch (e) {
+                serverDebugger('Error loading services for pattern: %j. Error: %o', patterns, e);
+                serverDebugger('ImportedTypes: %o', importedTypes);
+                throw new TypeError(
+                    `Error loading services for pattern: ${JSON.stringify(patterns)}. Error: ${e.message}`
+                );
+            }
+        }
+    }
+
+    /**
+     * Makes the server immutable. Any configuration change request to the Server
+     * is ignored when immutable is true
+     * @param value true to make immutable
+     */
+    public static immutable(value: boolean) {
+        Server.locked = value;
+    }
+
+    /**
+     * Return true if the server is immutable. Any configuration change request to the Server
+     * is ignored when immutable is true
+     */
+    public static isImmutable() {
+        return Server.locked;
+    }
+
+    /**
+     * Retrieve the express router that serves the rest endpoints
+     */
+    public static server() {
+        return ServerContainer.get().router;
+    }
+
+    /**
+     * Return all paths accepted by the Server
+     */
+    public static getPaths(): Array<string> {
+        const result = new Array<string>();
+        ServerContainer.get()
+            .getPaths()
+            .forEach((value) => {
+                result.push(value);
+            });
+
+        return result;
+    }
+
+    /**
+     * Register a custom serviceFactory. It will be used to instantiate the service Objects
+     * If You plan to use a custom serviceFactory, You must ensure to call this method before any typescript-rest service declaration.
+     */
+    public static registerServiceFactory(serviceFactory: ServiceFactory | string) {
+        if (!Server.locked) {
+            let factory: ServiceFactory;
+            if (typeof serviceFactory === 'string') {
+                const mod = require(serviceFactory);
+                factory = mod.default ? mod.default : mod;
+            } else {
+                factory = serviceFactory;
+            }
+
+            serverDebugger('Registering a new serviceFactory');
+            ServerContainer.get().serviceFactory = factory;
+        }
+    }
+
+    /**
+     * Register a service authenticator. It will be used to authenticate users before the service method
+     * invocations occurs.
+     */
+    public static registerAuthenticator(authenticator: ServiceAuthenticator, name: string = 'default') {
+        if (!Server.locked) {
+            serverDebugger('Registering a new authenticator with name %s', name);
+            ServerContainer.get().authenticator.set(name, authenticator);
+        }
+    }
+
+    /**
+     * Return the set oh HTTP verbs configured for the given path
+     * @param servicePath The path to search HTTP verbs
+     */
+    public static getHttpMethods(servicePath: string): Array<HttpMethod> {
+        const result = new Array<HttpMethod>();
+        ServerContainer.get()
+            .getHttpMethods(servicePath)
+            .forEach((value) => {
+                result.push(value);
+            });
+
+        return result;
+    }
+
+    /**
+     * A string used for signing cookies. This is optional and if not specified,
+     * will not parse signed cookies.
+     * @param secret the secret used to sign
+     */
+    public static setCookiesSecret(secret: string) {
+        if (!Server.locked) {
+            serverDebugger('Setting a new secret for cookies: %s', secret);
+            ServerContainer.get().cookiesSecret = secret;
+        }
+    }
+
+    /**
+     * Specifies a function that will be used to decode a cookie's value.
+     * This function can be used to decode a previously-encoded cookie value
+     * into a JavaScript string.
+     * The default function is the global decodeURIComponent, which will decode
+     * any URL-encoded sequences into their byte representations.
+     *
+     * NOTE: if an error is thrown from this function, the original, non-decoded
+     * cookie value will be returned as the cookie's value.
+     * @param decoder The decoder function
+     */
+    public static setCookiesDecoder(decoder: (val: string) => string) {
+        if (!Server.locked) {
+            serverDebugger('Setting a new secret decoder');
+            ServerContainer.get().cookiesDecoder = decoder;
+        }
+    }
+
+    /**
+     * Set where to store the uploaded files
+     * @param dest Destination folder
+     */
+    public static setFileDest(dest: string) {
+        if (!Server.locked) {
+            serverDebugger('Setting a new destination for files: %s', dest);
+            ServerContainer.get().fileDest = dest;
+        }
+    }
+
+    /**
+     * Set a Function to control which files are accepted to upload
+     * @param filter The filter function
+     */
+    public static setFileFilter(
+        filter: (
+            req: Express.Request,
+            file: Express.Multer.File,
+            callback: (error: Error, acceptFile: boolean) => void
+        ) => void
+    ) {
+        if (!Server.locked) {
+            serverDebugger('Setting a new filter for files');
+            ServerContainer.get().fileFilter = filter;
+        }
+    }
+
+    /**
+     * Set the limits of uploaded data
+     * @param limit The data limit
+     */
+    public static setFileLimits(limit: FileLimits) {
+        if (!Server.locked) {
+            serverDebugger('Setting a new fileLimits: %j', limit);
+            ServerContainer.get().fileLimits = limit;
+        }
+    }
+
+    /**
+     * Adds a converter for param values to have an ability to intercept the type that actually will be passed to service
+     * @param converter The converter
+     * @param type The target type that needs to be converted
+     */
+    public static addParameterConverter(converter: ParameterConverter, type: Function): void {
+        if (!Server.locked) {
+            serverDebugger('Adding a new parameter converter');
+            ServerContainer.get().paramConverters.set(type, converter);
+        }
+    }
+
+    /**
+     * Remove the converter associated with the given type.
+     * @param type The target type that needs to be converted
+     */
+    public static removeParameterConverter(type: Function): void {
+        if (!Server.locked) {
+            serverDebugger('Removing a parameter converter');
+            ServerContainer.get().paramConverters.delete(type);
+        }
+    }
+
+    /**
+     * Makes the server ignore next middlewares for all endpoints.
+     * It has the same effect than add @IgnoreNextMiddlewares to all
+     * services.
+     * @param value - true to ignore next middlewares.
+     */
+    public static ignoreNextMiddlewares(value: boolean) {
+        if (!Server.locked) {
+            serverDebugger('Ignoring next middlewares: %b', value);
+            ServerContainer.get().ignoreNextMiddlewares = value;
+        }
+    }
+
+    /**
+     * Creates and endpoint to publish the swagger documentation.
+     * @param router Express router
+     * @param options Options for swagger endpoint
+     */
+    public static swagger(router: express.Router, options?: SwaggerOptions) {
+        if (!Server.locked) {
+            const swaggerUi = require('swagger-ui-express');
+            options = Server.getOptions(options);
+            serverDebugger('Configuring open api documentation endpoints for options: %j', options);
+
+            const swaggerDocument: any = Server.loadSwaggerDocument(options);
+
+            if (options.host) {
+                swaggerDocument.host = options.host;
+            }
+            if (options.schemes) {
+                swaggerDocument.schemes = options.schemes;
+            }
+
+            router.get(path.posix.join('/', options.endpoint, 'json'), (req, res) => {
+                res.send(swaggerDocument);
+            });
+            router.get(path.posix.join('/', options.endpoint, 'yaml'), (req, res) => {
+                res.set('Content-Type', 'text/vnd.yaml');
+                res.send(YAML.stringify(swaggerDocument, 1000));
+            });
+            router.use(
+                path.posix.join('/', options.endpoint),
+                swaggerUi.serve,
+                swaggerUi.setup(swaggerDocument, options.swaggerUiOptions)
+            );
+        }
+    }
+
+    private static locked = false;
+
+    private static loadSwaggerDocument(options: SwaggerOptions) {
+        let swaggerDocument: any;
+        if (_.endsWith(options.filePath, '.yml') || _.endsWith(options.filePath, '.yaml')) {
+            swaggerDocument = YAML.load(options.filePath);
+        } else {
+            swaggerDocument = fs.readJSONSync(options.filePath);
+        }
+        serverDebugger('Loaded swagger configurations: %j', swaggerDocument);
+        return swaggerDocument;
+    }
+
+    private static getOptions(options: SwaggerOptions) {
+        options = _.defaults(options, {
+            endpoint: 'api-docs',
+            filePath: './swagger.json'
+        });
+        if (_.startsWith(options.filePath, '.')) {
+            options.filePath = path.join(process.cwd(), options.filePath);
+        }
+        return options;
+    }
+}
+
+export interface SwaggerOptions {
+    /**
+     * The path to a swagger file (json or yaml)
+     */
+    filePath?: string;
+    /**
+     * Where to publish the docs
+     */
+    endpoint?: string;
+    /**
+     * The hostname of the service
+     */
+    host?: string;
+    /**
+     * The schemes used by the server
+     */
+    schemes?: Array<string>;
+    /**
+     * Options to send to swagger-ui
+     */
+    swaggerUiOptions?: object;
+}

package/src/server/service-invoker.ts

@@ -0,0 +1,266 @@
+'use strict';
+
+import * as debug from 'debug';
+import * as express from 'express';
+import * as _ from 'lodash';
+import { Errors } from '../typescript-rest';
+import { ServiceClass, ServiceMethod, ServiceProperty } from './model/metadata';
+import { DownloadBinaryData, DownloadResource, NoResponse } from './model/return-types';
+import { HttpMethod, ReferencedResource, ServiceContext, ServiceProcessor } from './model/server-types';
+import { ParameterProcessor } from './parameter-processor';
+import { ServerContainer } from './server-container';
+
+export class ServiceInvoker {
+    private serviceClass: ServiceClass;
+    private serviceMethod: ServiceMethod;
+    private preProcessors: Array<ServiceProcessor>;
+    private postProcessors: Array<ServiceProcessor>;
+    private debugger = debug('typescript-rest:service-invoker:runtime');
+
+    constructor(serviceClass: ServiceClass, serviceMethod: ServiceMethod) {
+        this.serviceClass = serviceClass;
+        this.serviceMethod = serviceMethod;
+        this.preProcessors = _.union(serviceMethod.preProcessors, serviceClass.preProcessors);
+        this.postProcessors = _.union(serviceMethod.postProcessors, serviceClass.postProcessors);
+    }
+
+    public async callService(context: ServiceContext) {
+        try {
+            await this.callTargetEndPoint(context);
+            if (this.mustCallNext()) {
+                context.next();
+            } else if (this.debugger.enabled) {
+                this.debugger('Ignoring next middlewares');
+            }
+        } catch (err) {
+            context.next(err);
+        }
+    }
+
+    private mustCallNext() {
+        return (
+            !ServerContainer.get().ignoreNextMiddlewares &&
+            !this.serviceMethod.ignoreNextMiddlewares &&
+            !this.serviceClass.ignoreNextMiddlewares
+        );
+    }
+
+    private async runPreProcessors(context: ServiceContext): Promise<void> {
+        this.debugger('Running preprocessors');
+        for (const processor of this.preProcessors) {
+            await Promise.resolve(processor(context.request, context.response));
+        }
+    }
+
+    private async runPostProcessors(context: ServiceContext): Promise<void> {
+        this.debugger('Running postprocessors');
+        for (const processor of this.postProcessors) {
+            await Promise.resolve(processor(context.request, context.response));
+        }
+    }
+
+    private async callTargetEndPoint(context: ServiceContext) {
+        this.debugger('Calling targetEndpoint %s', this.serviceMethod.resolvedPath);
+        this.checkAcceptance(context);
+        if (this.preProcessors.length) {
+            await this.runPreProcessors(context);
+        }
+        const serviceObject = this.createService(context);
+        const args = this.buildArgumentsList(context);
+        const toCall = this.getMethodToCall();
+        if (this.debugger.enabled) {
+            this.debugger('Invoking service method <%s> with params: %j', this.serviceMethod.name, args);
+        }
+        const result = await toCall.apply(serviceObject, args);
+        if (this.postProcessors.length) {
+            await this.runPostProcessors(context);
+        }
+        this.processResponseHeaders(context);
+        await this.sendValue(result, context);
+    }
+
+    private getMethodToCall() {
+        return (
+            this.serviceClass.targetClass.prototype[this.serviceMethod.name] ||
+            this.serviceClass.targetClass[this.serviceMethod.name]
+        );
+    }
+
+    private checkAcceptance(context: ServiceContext): void {
+        this.debugger('Verifying accept headers');
+        this.identifyAcceptedLanguage(context);
+        this.identifyAcceptedType(context);
+
+        if (!context.accept) {
+            throw new Errors.NotAcceptableError('Accept');
+        }
+        if (!context.language) {
+            throw new Errors.NotAcceptableError('Accept-Language');
+        }
+    }
+
+    private identifyAcceptedLanguage(context: ServiceContext) {
+        if (this.serviceMethod.resolvedLanguages) {
+            const lang: any = context.request.acceptsLanguages(this.serviceMethod.resolvedLanguages);
+            if (lang) {
+                context.language = lang as string;
+            }
+        } else {
+            const languages: Array<string> = context.request.acceptsLanguages();
+            if (languages && languages.length > 0) {
+                context.language = languages[0];
+            }
+        }
+        this.debugger('Identified the preferable language accepted by server: %s', context.language);
+    }
+
+    private identifyAcceptedType(context: ServiceContext) {
+        if (this.serviceMethod.resolvedAccepts) {
+            context.accept = context.request.accepts(this.serviceMethod.resolvedAccepts) as string;
+        } else {
+            const accepts: Array<string> = context.request.accepts();
+            if (accepts && accepts.length > 0) {
+                context.accept = accepts[0];
+            }
+        }
+        this.debugger('Identified the preferable media type accepted by server: %s', context.accept);
+    }
+
+    private createService(context: ServiceContext) {
+        const serviceObject = ServerContainer.get().serviceFactory.create(this.serviceClass.targetClass, context);
+        this.debugger('Creating service object');
+        if (this.serviceClass.hasProperties()) {
+            this.serviceClass.properties.forEach((property, key) => {
+                this.debugger('Setting service property %s', key);
+                serviceObject[key] = this.processParameter(context, property);
+            });
+        }
+        return serviceObject;
+    }
+
+    private buildArgumentsList(context: ServiceContext) {
+        const result: Array<any> = new Array<any>();
+
+        this.serviceMethod.parameters.forEach((param) => {
+            this.debugger('Processing service parameter [%s]', param.name || 'body');
+            result.push(
+                this.processParameter(context, {
+                    name: param.name,
+                    propertyType: param.type,
+                    type: param.paramType
+                })
+            );
+        });
+
+        return result;
+    }
+
+    private processParameter(context: ServiceContext, property: ServiceProperty) {
+        return ParameterProcessor.get().processParameter(context, property);
+    }
+
+    private processResponseHeaders(context: ServiceContext) {
+        if (this.serviceMethod.resolvedLanguages) {
+            if (this.serviceMethod.httpMethod === HttpMethod.GET) {
+                this.debugger('Adding response header vary: Accept-Language');
+                context.response.vary('Accept-Language');
+            }
+            this.debugger('Adding response header Content-Language: %s', context.language);
+            context.response.set('Content-Language', context.language);
+        }
+        if (this.serviceMethod.resolvedAccepts) {
+            if (this.serviceMethod.httpMethod === HttpMethod.GET) {
+                this.debugger('Adding response header vary: Accept');
+                context.response.vary('Accept');
+            }
+        }
+    }
+
+    private async sendValue(value: any, context: ServiceContext) {
+        if (value !== NoResponse) {
+            this.debugger('Sending response value: %o', value);
+            switch (typeof value) {
+                case 'number':
+                    context.response.send(value.toString());
+                    break;
+                case 'string':
+                    context.response.send(value);
+                    break;
+                case 'boolean':
+                    context.response.send(value.toString());
+                    break;
+                case 'undefined':
+                    if (!context.response.headersSent) {
+                        context.response.sendStatus(204);
+                    }
+                    break;
+                default:
+                    if (value === null) {
+                        context.response.send(value);
+                    } else {
+                        await this.sendComplexValue(context, value);
+                    }
+            }
+        } else {
+            this.debugger('Do not send any response value');
+        }
+    }
+
+    private async sendComplexValue(context: ServiceContext, value: any) {
+        if (value.filePath && value instanceof DownloadResource) {
+            await this.downloadResToPromise(context.response, value);
+        } else if (value instanceof DownloadBinaryData) {
+            this.sendFile(context, value);
+        } else if (value.location && value instanceof ReferencedResource) {
+            await this.sendReferencedResource(context, value);
+        } else if (value.then && value.catch) {
+            const val = await value;
+            await this.sendValue(val, context);
+        } else {
+            this.debugger('Sending a json value: %j', value);
+            context.response.json(value);
+        }
+    }
+
+    private async sendReferencedResource(context: ServiceContext, value: ReferencedResource<any>) {
+        this.debugger('Setting the header Location: %s', value.location);
+        this.debugger('Sendinf status code: %d', value.statusCode);
+        context.response.set('Location', value.location);
+        if (value.body) {
+            context.response.status(value.statusCode);
+            await this.sendValue(value.body, context);
+        } else {
+            context.response.sendStatus(value.statusCode);
+        }
+    }
+
+    private sendFile(context: ServiceContext, value: DownloadBinaryData) {
+        this.debugger('Sending file as response');
+        if (value.fileName) {
+            context.response.writeHead(200, {
+                'Content-Length': value.content.length,
+                'Content-Type': value.mimeType,
+                'Content-disposition': 'attachment;filename=' + value.fileName
+            });
+        } else {
+            context.response.writeHead(200, {
+                'Content-Length': value.content.length,
+                'Content-Type': value.mimeType
+            });
+        }
+        context.response.end(value.content);
+    }
+
+    private downloadResToPromise(res: express.Response, value: DownloadResource) {
+        this.debugger('Sending a resource to download. Path: %s', value.filePath);
+        return new Promise((resolve, reject) => {
+            res.download(value.filePath, value.fileName || value.filePath, (err) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve(undefined);
+                }
+            });
+        });
+    }
+}

package/src/typescript-rest.ts

@@ -0,0 +1,16 @@
+'use strict';
+
+import { ServerConfig } from './server/config';
+import * as Errors from './server/model/errors';
+import * as Return from './server/model/return-types';
+
+export * from './decorators/methods';
+export * from './decorators/parameters';
+export * from './decorators/services';
+export * from './server/model/server-types';
+export * from './server/server';
+
+export { DefaultServiceFactory } from './server/server-container';
+export { Errors, Return };
+
+ServerConfig.configure();