@nmshd/typescript-rest 3.0.5

package/src/decorators/services.ts

@@ -0,0 +1,390 @@
+'use strict';
+
+import * as _ from 'lodash';
+import 'reflect-metadata';
+import { ServiceClass, ServiceMethod } from '../server/model/metadata';
+import { ParserType, ServiceProcessor } from '../server/model/server-types';
+import { ServerContainer } from '../server/server-container';
+
+/**
+ * A decorator to tell the [[Server]] that a class or a method
+ * should be bound to a given path.
+ *
+ * For example:
+ *
+ * ```
+ * @ Path('people')
+ * class PeopleService {
+ *   @ PUT
+ *   @ Path(':id')
+ *   savePerson(person:Person) {
+ *      // ...
+ *   }
+ *
+ *   @ GET
+ *   @ Path(':id')
+ *   getPerson():Person {
+ *      // ...
+ *   }
+ * }
+ * ```
+ *
+ * Will create services that listen for requests like:
+ *
+ * ```
+ * PUT http://mydomain/people/123 or
+ * GET http://mydomain/people/123
+ * ```
+ */
+export function Path(path: string) {
+    return new ServiceDecorator('Path').withProperty('path', path).createDecorator();
+}
+
+/**
+ * A decorator to tell the [[Server]] that a class or a method
+ * should include a determined role
+ * or all authorized users (token) using passport
+ *
+ * For example:
+ *
+ * ```
+ * @ Path('people')
+ * @ Security()
+ * class PeopleService {
+ *   @ PUT
+ *   @ Path(':id', true)
+ *   @ Security(['ROLE_ADMIN'])
+ *   savePerson(person:Person) {
+ *      // ...
+ *   }
+ *
+ *   @ GET
+ *   @ Path(':id', true)
+ *   getPerson():Person {
+ *      // ...
+ *   }
+ * }
+ * ```
+ *
+ * Will create services that listen for requests like:
+ *
+ * ```
+ * PUT http://mydomain/people/123 (Only for ADMIN roles) or
+ * GET http://mydomain/people/123 (For all authorized users)
+ * ```
+ */
+export function Security(roles?: string | Array<string>, name?: string) {
+    roles = _.castArray(roles || '*');
+    return new SecurityServiceDecorator('Security')
+        .withObjectProperty('authenticator', name || 'default', roles)
+        .createDecorator();
+}
+
+/**
+ * A decorator to tell the [[Server]] that a class or a method
+ * should include a pre-processor in its request pipelines.
+ *
+ * For example:
+ * ```
+ * function validator(req: express.Request): express.Request {
+ *   if (!req.body.userId) {
+ *      throw new Errors.BadRequestError("userId not present");
+ *   }
+ * }
+ * ```
+ * And:
+ *
+ * ```
+ * @ Path('people')
+ * class PeopleService {
+ *   @ PUT
+ *   @ Path(':id')
+ *   @ PreProcessor(validator)
+ *   savePerson(person:Person) {
+ *      // ...
+ *   }
+ * }
+ * ```
+ */
+export function PreProcessor(preprocessor: ServiceProcessor) {
+    return new ProcessorServiceDecorator('PreProcessor')
+        .withArrayProperty('preProcessors', preprocessor, true)
+        .createDecorator();
+}
+
+/**
+ * A decorator to tell the [[Server]] that a class or a method
+ * should include a post-processor in its request pipelines.
+ *
+ * For example:
+ * ```
+ * function processor(req: express.Request): express.Request {
+ *   if (!req.body.userId) {
+ *      throw new Errors.BadRequestError("userId not present");
+ *   }
+ * }
+ * ```
+ * And:
+ *
+ * ```
+ * @ Path('people')
+ * class PeopleService {
+ *   @ PUT
+ *   @ Path(':id')
+ *   @ PostProcessor(validator)
+ *   savePerson(person:Person) {
+ *      // ...
+ *   }
+ * }
+ * ```
+ */
+export function PostProcessor(postprocessor: ServiceProcessor) {
+    return new ProcessorServiceDecorator('PostProcessor')
+        .withArrayProperty('postProcessors', postprocessor, true)
+        .createDecorator();
+}
+
+/**
+ * A decorator to tell the [[Server]] that a class or a method
+ * should only accept requests from clients that accepts one of
+ * the supported languages.
+ *
+ * For example:
+ *
+ * ```
+ * @ Path('accept')
+ * @ AcceptLanguage('en', 'pt-BR')
+ * class TestAcceptService {
+ *      // ...
+ * }
+ * ```
+ *
+ * Will reject requests that only accepts languages that are not
+ * English or Brazilian portuguese
+ *
+ * If the language requested is not supported, a status code 406 returned
+ */
+export function AcceptLanguage(...languages: Array<string>) {
+    languages = _.compact(languages);
+    return new AcceptServiceDecorator('AcceptLanguage')
+        .withArrayProperty('languages', languages, true)
+        .createDecorator();
+}
+
+/**
+ * A decorator to tell the [[Server]] that a class or a method
+ * should only accept requests from clients that accepts one of
+ * the supported mime types.
+ *
+ * For example:
+ *
+ * ```
+ * @ Path('accept')
+ * @ Accept('application/json')
+ * class TestAcceptService {
+ *      // ...
+ * }
+ * ```
+ *
+ * Will reject requests that only accepts mime types that are not
+ * 'application/json'
+ *
+ * If the mime type requested is not supported, a status code 406 returned
+ */
+export function Accept(...accepts: Array<string>) {
+    accepts = _.compact(accepts);
+    return new AcceptServiceDecorator('Accept').withArrayProperty('accepts', accepts, true).createDecorator();
+}
+
+/**
+ * A decorator to inform options to pe passed to bodyParser.
+ * You can inform any property accepted by
+ * [[bodyParser]](https://www.npmjs.com/package/body-parser)
+ */
+export function BodyOptions(options: any) {
+    return new ServiceDecorator('BodyOptions').withProperty('bodyParserOptions', options).createDecorator();
+}
+
+/**
+ * A decorator to inform the type of parser to be used to parse the body.
+ * The default type is json.
+ */
+export function BodyType(type: ParserType) {
+    return new ServiceDecorator('BodyType').withProperty('bodyParserType', type).createDecorator();
+}
+
+/**
+ * A decorator to inform that server should ignore other middlewares.
+ * It makes server does not call next function after service invocation.
+ */
+export function IgnoreNextMiddlewares(...args: Array<any>) {
+    return new ServiceDecorator('IgnoreNextMiddlewares')
+        .withProperty('ignoreNextMiddlewares', true)
+        .decorateTypeOrMethod(args);
+}
+
+/**
+ * Mark the annotated service class as an abstract service. Abstract services has none of its
+ * methods exposed as rest enpoints, even if the class is in the services list to be exposed.
+ *
+ * For example:
+ *
+ * ```
+ * @ Abstract
+ * abstract class PeopleService {
+ *   @ GET
+ *   getPeople(@ Param('name') name: string) {
+ *      // ...
+ *   }
+ * }
+ * ```
+ *
+ * No endpoint will be registered for PeopleService. It is useful if you only plain that subclasses of
+ * PeopleService exposes the getPeople method.
+ */
+export function Abstract(...args: Array<any>) {
+    args = _.without(args, undefined);
+    if (args.length === 1) {
+        const classData: ServiceClass = ServerContainer.get().registerServiceClass(args[0]);
+        classData.isAbstract = true;
+    } else {
+        throw new Error('Invalid @Abstract Decorator declaration.');
+    }
+}
+
+interface DecoratorProperty {
+    property: string;
+    value: any;
+    required: boolean;
+    process: (target: any) => void;
+    checkRequired: () => boolean;
+}
+
+class ServiceDecorator {
+    protected decorator: string;
+    protected properties: Array<DecoratorProperty> = [];
+
+    constructor(decorator: string) {
+        this.decorator = decorator;
+    }
+
+    public withProperty(property: string, value: any, required: boolean = false) {
+        this.properties.push({
+            checkRequired: () => required && !value,
+            process: (target: any) => {
+                target[property] = value;
+            },
+            property: property,
+            required: required,
+            value: value
+        });
+        return this;
+    }
+
+    public createDecorator() {
+        return (...args: Array<any>) => {
+            this.checkRequiredValue();
+            this.decorateTypeOrMethod(args);
+        };
+    }
+
+    public decorateTypeOrMethod(args: Array<any>) {
+        args = _.without(args, undefined);
+        if (args.length === 1) {
+            this.decorateType(args[0]);
+        } else if (args.length === 3 && typeof args[2] === 'object') {
+            this.decorateMethod(args[0], args[1]);
+        } else {
+            throw new Error(`Invalid @${this.decorator} Decorator declaration.`);
+        }
+    }
+
+    protected checkRequiredValue() {
+        this.properties.forEach((property) => {
+            if (property.checkRequired()) {
+                throw new Error(`Invalid @${this.decorator} Decorator declaration.`);
+            }
+        });
+    }
+
+    protected decorateType(target: Function) {
+        const classData: ServiceClass = ServerContainer.get().registerServiceClass(target);
+        if (classData) {
+            this.updateClassMetadata(classData);
+        }
+    }
+
+    protected decorateMethod(target: Function, propertyKey: string) {
+        const serviceMethod: ServiceMethod = ServerContainer.get().registerServiceMethod(
+            target.constructor,
+            propertyKey
+        );
+        if (serviceMethod) {
+            // does not intercept constructor
+            this.updateMethodMetadada(serviceMethod);
+        }
+    }
+
+    protected updateClassMetadata(classData: ServiceClass) {
+        this.properties.forEach((property) => {
+            property.process(classData);
+        });
+    }
+
+    protected updateMethodMetadada(serviceMethod: ServiceMethod) {
+        this.properties.forEach((property) => {
+            property.process(serviceMethod);
+        });
+    }
+}
+
+class SecurityServiceDecorator extends ServiceDecorator {
+    public withObjectProperty(property: string, subtext: string, value: any, required: boolean = false) {
+        this.properties.push({
+            checkRequired: () => required && !value,
+            process: (target: any) => {
+                if (!target[property]) {
+                    target[property] = {};
+                }
+                target[property][subtext] = value;
+            },
+            property: property,
+            required: required,
+            value: value
+        });
+        return this;
+    }
+}
+
+class ProcessorServiceDecorator extends ServiceDecorator {
+    public withArrayProperty(property: string, value: any, required: boolean = false) {
+        this.properties.push({
+            checkRequired: () => required && !value,
+            process: (target: any) => {
+                if (!target[property]) {
+                    target[property] = [];
+                }
+                target[property].unshift(value);
+            },
+            property: property,
+            required: required,
+            value: value
+        });
+        return this;
+    }
+}
+
+class AcceptServiceDecorator extends ServiceDecorator {
+    public withArrayProperty(property: string, value: any, required: boolean = false) {
+        this.properties.push({
+            checkRequired: () => required && (!value || !value.length),
+            process: (target: any) => {
+                target[property] = _.union(target[property], value);
+            },
+            property: property,
+            required: required,
+            value: value
+        });
+        return this;
+    }
+}

package/src/server/config.ts

@@ -0,0 +1,40 @@
+import * as debug from 'debug';
+import * as fs from 'fs-extra';
+import * as path from 'path';
+import { Server } from './server';
+
+const serverDebugger = debug('typescript-rest:server:config:build');
+
+export class ServerConfig {
+    public static configure() {
+        try {
+            const CONFIG_FILE = this.searchConfigFile();
+            if (CONFIG_FILE && fs.existsSync(CONFIG_FILE)) {
+                const config = fs.readJSONSync(CONFIG_FILE);
+                serverDebugger('rest.config file found: %j', config);
+                if (config.serviceFactory) {
+                    if (config.serviceFactory.indexOf('.') === 0) {
+                        config.serviceFactory = path.join(process.cwd(), config.serviceFactory);
+                    }
+                    Server.registerServiceFactory(config.serviceFactory);
+                }
+            }
+        } catch (e) {
+            // eslint-disable-next-line no-console
+            console.error(e);
+        }
+    }
+
+    public static searchConfigFile() {
+        serverDebugger('Searching for rest.config file');
+        let configFile = path.join(__dirname, 'rest.config');
+        while (!fs.existsSync(configFile)) {
+            const fileOnParent = path.normalize(path.join(path.dirname(configFile), '..', 'rest.config'));
+            if (configFile === fileOnParent) {
+                return null;
+            }
+            configFile = fileOnParent;
+        }
+        return configFile;
+    }
+}

package/src/server/model/errors.ts

@@ -0,0 +1,178 @@
+'use strict';
+
+/**
+ * The Base class for all HTTP errors
+ */
+export abstract class HttpError extends Error {
+    public statusCode: number;
+
+    constructor(
+        name: string,
+        public message: string
+    ) {
+        super(message);
+        this.name = name;
+    }
+}
+
+/**
+ * Represents a BAD REQUEST error. The request could not be understood by the
+ * server due to malformed syntax. The client SHOULD NOT repeat the request
+ * without modifications.
+ */
+export class BadRequestError extends HttpError {
+    constructor(message?: string) {
+        super('BadRequestError', message || 'Bad Request');
+        Object.setPrototypeOf(this, BadRequestError.prototype);
+        this.statusCode = 400;
+    }
+}
+
+/**
+ * Represents an UNAUTHORIZED error. The request requires user authentication. The response
+ * MUST include a WWW-Authenticate header field containing a challenge applicable to the
+ * requested resource.
+ */
+export class UnauthorizedError extends HttpError {
+    constructor(message?: string) {
+        super('UnauthorizedError', message || 'Unauthorized');
+        Object.setPrototypeOf(this, UnauthorizedError.prototype);
+        this.statusCode = 401;
+    }
+}
+
+/**
+ * Represents a FORBIDDEN error. The server understood the request, but is refusing to
+ * fulfill it. Authorization will not help and the request SHOULD NOT be repeated.
+ */
+export class ForbiddenError extends HttpError {
+    constructor(message?: string) {
+        super('ForbiddenError', message || 'Forbidden');
+        Object.setPrototypeOf(this, ForbiddenError.prototype);
+        this.statusCode = 403;
+    }
+}
+
+/**
+ * Represents a NOT FOUND error. The server has not found anything matching
+ * the Request-URI. No indication is given of whether the condition is temporary
+ * or permanent. The 410 (GoneError) status code SHOULD be used if the server knows,
+ * through some internally configurable mechanism, that an old resource is permanently
+ * unavailable and has no forwarding address.
+ *
+ * This error is commonly used when
+ * the server does not wish to reveal exactly why the request has been refused,
+ * or when no other response is applicable.
+ */
+export class NotFoundError extends HttpError {
+    constructor(message?: string) {
+        super('NotFoundError', message || 'Not Found');
+        Object.setPrototypeOf(this, NotFoundError.prototype);
+        this.statusCode = 404;
+    }
+}
+
+/**
+ * Represents a METHOD NOT ALLOWED error. The method specified in the Request-Line is not allowed for
+ * the resource identified by the Request-URI. The response MUST include an Allow header
+ * containing a list of valid methods for the requested resource.
+ */
+export class MethodNotAllowedError extends HttpError {
+    constructor(message?: string) {
+        super('MethodNotAllowedError', message || 'Method Not Allowed');
+        Object.setPrototypeOf(this, MethodNotAllowedError.prototype);
+        this.statusCode = 405;
+    }
+}
+
+/**
+ * Represents a NOT ACCEPTABLE error. The resource identified by the request is only capable of
+ * generating response entities which have content characteristics not acceptable according
+ * to the accept headers sent in the request.
+ */
+export class NotAcceptableError extends HttpError {
+    constructor(message?: string) {
+        super('NotAcceptableError', message || 'Not Acceptable');
+        Object.setPrototypeOf(this, NotAcceptableError.prototype);
+        this.statusCode = 406;
+    }
+}
+/**
+ * Represents a CONFLICT error. The request could not be completed due to a
+ * conflict with the current state of the resource.
+ */
+export class ConflictError extends HttpError {
+    constructor(message?: string) {
+        super('ConflictError', message || 'Conflict');
+        Object.setPrototypeOf(this, ConflictError.prototype);
+        this.statusCode = 409;
+    }
+}
+
+/**
+ * Represents a GONE error. The requested resource is no longer available at the server
+ * and no forwarding address is known. This condition is expected to be considered
+ * permanent. Clients with link editing capabilities SHOULD delete references to
+ * the Request-URI after user approval. If the server does not know, or has
+ * no facility to determine, whether or not the condition is permanent, the
+ * error 404 (NotFoundError) SHOULD be used instead. This response is
+ * cacheable unless indicated otherwise.
+ */
+export class GoneError extends HttpError {
+    constructor(message?: string) {
+        super('GoneError', message || 'Gone');
+        Object.setPrototypeOf(this, GoneError.prototype);
+        this.statusCode = 410;
+    }
+}
+
+/**
+ * Represents an UNSUPPORTED MEDIA TYPE error. The server is refusing to service the request
+ * because the entity of the request is in a format not supported by the requested resource
+ * for the requested method.
+ */
+export class UnsupportedMediaTypeError extends HttpError {
+    constructor(message?: string) {
+        super('UnsupportedMediaTypeError', message || 'Unsupported Media Type');
+        Object.setPrototypeOf(this, UnsupportedMediaTypeError.prototype);
+        this.statusCode = 415;
+    }
+}
+
+/**
+ * Represents a UNPROCESSABLE ENTITY error. The server understands the content type of the request entity
+ * (hence a 415 Unsupported Media Type status code is inappropriate), and the syntax of the request entity is correct
+ * (thus a 400 Bad Request status code is inappropriate) but was unable to process the contained instructions.
+ */
+export class UnprocessableEntityError extends HttpError {
+    constructor(message?: string) {
+        super('UnprocessableEntityError', message || 'Unprocessable Entity');
+        Object.setPrototypeOf(this, UnprocessableEntityError.prototype);
+        this.statusCode = 422;
+    }
+}
+
+/**
+ * Represents an INTERNAL SERVER error. The server encountered an unexpected condition
+ * which prevented it from fulfilling the request.
+ */
+export class InternalServerError extends HttpError {
+    constructor(message?: string) {
+        super('InternalServerError', message || 'Internal Server Error');
+        Object.setPrototypeOf(this, InternalServerError.prototype);
+        this.statusCode = 500;
+    }
+}
+
+/**
+ * Represents a NOT IMPLEMENTED error. The server does not support the functionality required
+ *  to fulfill the request. This is the appropriate response when the server does not recognize
+ * the request method and is not capable of supporting it for any resource.
+ */
+export class NotImplementedError extends HttpError {
+    constructor(message?: string) {
+        super('NotImplementedError', message || 'Not Implemented');
+        Object.setPrototypeOf(this, NotImplementedError.prototype);
+        this.statusCode = 501;
+    }
+}