Noncommital Premarital Mischief

    @sugoi/server
    TypeScript icon, indicating that this package has built-in type declarations

    4.1.0 • Public • Published

    @Sugoi/Server

    Sugoi logo

    npm version Build Status codecov

    Introduction

    SugoiJS is a minimal modular framework.

    SugoiJS gives you the ability to use only what you need and do it fast.

    this is a standalone module that can be functional on its own (as all of the SugoiJS modules).

    This module provides singleton services, request handling decorators and request policies decorators.

    SugoiJS server uses inversify, inversify-express-utils and re-export those modules

    Installation

    npm install --save @sugoi/server

    or use @sugoi/cli

    tsconfig.json:

    Under your tsconfig - compilerOptions set:

    • "target": "es5"

    • "emitDecoratorMetadata": true

    • "experimentalDecorators": true

    • "lib": ["es2015","dom"]

    TSConfig Template

    You are able to use the config template which was set for the @sugoi/demo application:

    {
      "compilerOptions": {
        "baseUrl": "./src",
        "allowJs": true,
        "target": "es5",
        "module": "commonjs",
        "moduleResolution": "node",
        "sourceMap": true,
        "emitDecoratorMetadata": true,
        "experimentalDecorators": true,
        "lib": [
          "es2015",
          "dom"
        ],
        "typeRoots": [
          "./node_modules/@types"
        ],
        "types": [
          "body-parser",
          "express",
          "node"
        ]
      }
    }
    

    Bootstrapping

    To bootstrap you server use the 'init' method:

    init(boostrapModule: any, rootPath?: string, authProvider?: AuthProvider)
    

    when boostrapModule is the entry point module

    rootPath - Server uri prefix

    import {HttpServer} from "@sugoi/server";
    
    const server:HttpServer = HttpServer.init(ServerModule,"/api");
    

    Migrate existing project

    SugoiJS support migrate existing project by providing hybrid mode.

    For achieving this approach use the initializeFrom method

    HttpServer.initializeFrom(sourceApp: TServer, bootstrapModule: any, authProvider?: TNewable<AuthProvider>)

    TServer - http.Server | https.Server | { listen: (...args) => any }

    Example:

    import {HttpServer} from "@sugoi/server";
    
    const server:HttpServer = HttpServer.initializeFrom(myExpressApp,ServerModule);
    

    Build & listen

    After setting the middlewares and error handlers, build and listen to requests by:

    server//HttpServer instance
        .setStatic("assets")
        .setMiddlewares((app) => {
            app.use(bodyParser.json());
            app.use(compression());
        })
        .setErrorHandlers((app) => {
            app.use(function (req, res, next) {
                return res.sendFile(path.resolve(paths.index))
            });
            app.use((req,res,next)=>{
                return function(err){
                    if(err instanceof SugoiServerError){
                        console.log.error(err.stack);
                        console.log.error(`${err.message} ${JSON.stringify(err.data)});
                        res.status(500).send("Internal error");
                    }
                }
            });
        })
    	.listen(PORT, (error: Error) => {
    	            if (error) {
    	                logger.error(error.message);
    	                throw error;
    	            }
    	            logger.debug(`Server running @ ${HOST}:${PORT}`);
        });
    

    This call will return http.Server instance which can be use for setting app variables, socket server and more.

    Set module

    Creating a module requires you to should use the @ServerModule decorator

    import {ServerModule} from "@sugoi/server"
    @ServerModule({
        controllers:[CoreController],
        services: [CoreService],
        modules:[LoginModule,DashboardModule]
    })
    export class ServerModule{
        constructor(){}
    }
    

    Set controller

    SugoiJS use inversify-express-utils decorators and re-export them (also with alias to capitalize camel-case decorator names)

    import {Controller,Response,HttpGet,RequestParam} from "@sugoi/server";
    
    @Controller('/dashboard')
    export class CoreController{
        constructor(){}
    
        @HttpGet("/:role")
        test(@response() response,@requestParam('role') role){
            if(role === "user" )
                return "authorized";
            else{
                throw new Error("unauthorized")
            }
        }
    }
    

    Further information can be found on Inversify-express-utils documentation

    Set service

    For setting class as service the class must be decorated with @Injectable decorator, this will set the class as singleton.

    @Injectable()
    class MyService{
        public listeners:number = 0;
    
        public incListeners(){
            this.listeners++;
        }
    
        public decListeners(){
            this.listeners--;
        }
    }
    

    later we will be able to inject the service instance by:

    Variable binding

    • @Inject(MyService) private myService:MyService

    • @Inject("MyService") private myService:MyService

    • constructor(private myService:MyService)

    Return the value from the "container"

    The InversifyJS container is handling the singleton objects.

    The container is stored on the server instance, each request and the ServerContainerService by the instanceId

    • server.container

    • req.container

    • ServerContainerService.getContainerById(serverInstanceId)

    After retriving the container we will able to get the service instance:

    • private myService:MyService = container.get(MyService)

    • private myService:MyService = container.get("MyService")

    Setting middlewares and Error handlers

    For setting static file serving use:

    setStatic(pathToStatic:string,route?:string)
    

    For setting middlewares use:

    setMiddlewares(...(app)=>void)
    

    For setting error handlers use:

    setErrorHandlers((app) => void)
    

    Full example:

    (<HttpServer>server)
        .setStatic("assets/admin","/admin")
        .setStatic("assets/main")
        .setMiddlewares((app) => {
            app.use(bodyParser.json());
            app.use(compression());
        })
        .setErrorHandlers((app) => {
            app.use(function (req, res, next) {
                return res.sendFile(path.resolve(paths.index))
            });
            app.use((req,res,next)=>{
                return function(err){
                    if(err instanceof SugoiServerError){
                        console.log.error(err.stack);
                        console.log.error(`${err.message} ${JSON.stringify(err.data)});
                        res.status(500).send("Internal error");
                    }
                }
            });
        });
    

    Policies

    @sugoi/server uses @sugoi/core policies and supply predefined policies.

    And re-export SchemaTypes, TPolicy, TComparableSchema, Policy, UsePolicy, ComparableSchema from "@sugoi/core";

    Further information on the @sugoi/core package documentation

    RequestSchemaPolicy

    /**
     *  paramSchema         - req.params
     *  queryParamSchema    - req.query
     *  bodySchema          - req.body
     *  headersSchema       - req.headers
     **/
    RequestSchemaPolicy(paramSchema?: TComparableSchema,queryParamSchema?: TComparableSchema,bodySchema?: TComparableSchema,headersSchema?: TComparableSchema)
    

    The RequestSchemaPolicy decorator use for validate the request is using a valid schema for params\queryParams\body\headers.

    In case null will pass the value won't check.

    Example:

    @Controller('/dashboard')
    export class DashboardController {
        constructor() {
        }
    
        @HttpPost("/:id")
        @RequestSchemaPolicy({"id": ComparableSchema.ofType(SchemaTypes.NUMBER)},
                              null,
                              {"role": ComparableSchema.ofType({text: ComparableSchema.ofType(SchemaTypes.STRING).setRegex("([A-Z])+","i")})})
                              //body schema is {role:{text:string//with regex /([A-Z])+/i}}
        getUser(@RequestParam("id") id:number, @RequestBody("role") role:{text:string}) {
            return User.findOne({id,role:role.text})
        }
    
    }
    

    Authorization

    Authorized

    /**
     *  requiredRole: TStringOrNumber|TStringOrNumber[] - The required role(s)
     *  permissions: TStringOrNumber|TStringOrNumber[]  - The required premission(s)
     *  failedCode: number                              - The response code in case the policy will fail
     **/
    Authorized(requiredRole: TStringOrNumber|TStringOrNumber[] = null, permissions: TStringOrNumber|TStringOrNumber[] = null, failedCode: number = 401)
    

    The Authorized decorator use for validate the user is Authorized and in the right role and permissions(optional).

    In case null will pass the value won't check.

    The Authorized policy will use the AuthProvider which pass while the server init: init(boostrapModule: any, rootPath?: string, moduleMetaKey?: string, authProvider?: AuthProvider)

    The AuthProvider will init for each request, the AuthProvider holding the request headers & cookies.

    Example:

    Authorization.class.ts:
    export class Authorization extends AuthProvider<User> {
    
    
        /**
         * Verify if user is authorized
         *
         * Implemented dummy check for x-sug-demo header to be equal to "Wyn1RRR9PQJPaqYM"
         *
         * @returns {Promise<boolean>}
         */
        isAuthenticated(): Promise<boolean> {
            return Promise.resolve(this.headers["x-sug-demo"] === "Wyn1RRR9PQJPaqYM");
        }
    
        getUser(req?: e.Request, res?: e.Response, next?: e.NextFunction): Promise<any> {
            return this.details 
                ?   Promise.resolve(this.details)
                : UserService.getUser(UserService.getIdFromCookie(this.cookie))
                              .then((user:User)=>{
                                this.details = user;
                                return user;
                              })
        }
    
        isInRole(...roles: Array<string | number>): Promise<boolean> {
            return this.getUser().then(user=>roles.includes(user.role));
    
        }
        
        /**
        * Check if on of user has some of the permissions.
        **/
        isAllowedTo(...permissions: Array<string | number>): Promise<boolean> {
            return this.getUser().then(user=>permissions.some(permission=>user.permissions.includes(permission)));
        }
        
        isResourceOwner(resourceId: any): Promise<boolean> {
            return this.getUser().then(user=>Resources.checkIfOwner(resourceId,user.id));
        }
    
    }
    
    app.ts:
    `init(boostrapModule,"/",null, Authorization)`
    
    dashboard.controller.ts:
    @Controller('/dashboard')
    export class DashboardController {
        constructor() {
        }
    
        @HttpPost("/:id")
        @Authorized(["User","Admin"],"User.READ")
        @Authorized(null,"User.READ_BY_ID") // This case promise the user have both "User.READ" AND "User.READ_BY_ID" permissions
        getUser(@RequestParam("id") id:number, @RequestBody("role") role:{text:string}) {
            return User.findOne({id,role:role.text})
        }
    
    }
    

    Documentation

    You can find further information on Sugoi official website

    Install

    npm i @sugoi/server

    Homepage

    sugoijs.com

    DownloadsWeekly Downloads

    257

    Version

    4.1.0

    License

    MIT

    Unpacked Size

    282 kB

    Total Files

    214

    Last publish

    Collaborators

    • o.b.one