node-server-engine 1.0.5

package/src/entities/Endpoint/Endpoint.test.ts

@@ -0,0 +1,337 @@
+import { randomUUID } from 'crypto';
+import { generateAccessToken } from 'backend-test-tools';
+import { expect } from 'chai';
+import express, { Request, Response, NextFunction } from 'express';
+import { faker } from '@faker-js/faker';
+import { fake } from 'sinon';
+import request from 'supertest';
+import { Endpoint } from './Endpoint';
+import {
+  EndpointMethod,
+  EndpointAuthType,
+  EndpointOptions
+} from './Endpoint.types';
+import { Server } from 'entities/Server';
+import { request as httpRequest } from 'utils/request';
+import { tlsRequest } from 'utils/tlsRequest';
+
+const PATH = '/test';
+let app = express();
+
+const config: EndpointOptions<EndpointAuthType.NONE> = {
+  method: EndpointMethod.GET,
+  path: PATH,
+  handler: (req: Request, res: Response) => {
+    res.sendStatus(200);
+  },
+  validator: {},
+  authType: EndpointAuthType.NONE
+};
+
+describe('Entity - Endpoint', () => {
+  beforeEach(() => {
+    app = express();
+  });
+
+  // Base
+
+  it('should create a valid Endpoint', async () => {
+    const endpoint = new Endpoint(config);
+    endpoint.register(app);
+    await request(app).get(PATH).expect(200);
+  });
+
+  // Async
+
+  it('should handle asynchronous errors', async () => {
+    const endpoint = new Endpoint({
+      ...config,
+      handler: async (): Promise<void> => {
+        return new Promise((resolve, reject) => {
+          reject(new Error());
+        });
+      }
+    });
+    endpoint.register(app);
+    await request(app).get(PATH).expect(500);
+  });
+
+  // Middleware
+
+  it('should handle specific middleware', async () => {
+    const middleware = fake(
+      (req: Request, res: Response, next: NextFunction) => {
+        next();
+      }
+    );
+    const endpoint = new Endpoint({
+      ...config,
+      middleware: [middleware]
+    });
+    endpoint.register(app);
+    await request(app).get(PATH).expect(200);
+    expect(middleware).to.have.been.called;
+  });
+
+  it('should handle specific error middleware', async () => {
+    const middleware = fake(
+      (err: Error, req: Request, res: Response, next: NextFunction) => {
+        res.sendStatus(200);
+      }
+    );
+    const endpoint = new Endpoint({
+      ...config,
+      handler: (): void => {
+        throw new Error();
+      },
+      errorMiddleware: [middleware]
+    });
+    endpoint.register(app);
+    await request(app).get(PATH).expect(200);
+    expect(middleware).to.have.been.called;
+  });
+
+  // Validator
+
+  it('should accept request with a valid shape', async () => {
+    const endpoint = new Endpoint({
+      ...config,
+      validator: { number: { in: 'query', isInt: true } }
+    });
+    endpoint.register(app);
+    await request(app)
+      .get(PATH)
+      .query({ number: faker.number.int() })
+      .expect(200);
+  });
+
+  it('should reject request with an invalid shape', async () => {
+    const endpoint = new Endpoint({
+      ...config,
+      validator: { number: { in: 'query', isInt: true } }
+    });
+    endpoint.register(app);
+    await request(app)
+      .get(PATH)
+      .query({ number: faker.lorem.word() })
+      .expect(400);
+  });
+
+  // Middleware
+  it('should inject middlewares', async () => {
+    const middleware = fake(
+      (req: Request, res: Response, next: NextFunction) => {
+        next();
+      }
+    );
+    const endpoint = new Endpoint({
+      ...config,
+      middleware
+    });
+    endpoint.register(app);
+    await request(app).get(PATH).expect(200);
+    expect(middleware.called).to.be.true;
+  });
+
+  it('should inject multiple middlewares', async () => {
+    const middleware = [
+      fake((req: Request, res: Response, next: NextFunction) => {
+        next();
+      }),
+      fake((req: Request, res: Response, next: NextFunction) => {
+        next();
+      })
+    ];
+    const endpoint = new Endpoint({
+      ...config,
+      middleware
+    });
+    endpoint.register(app);
+    await request(app).get(PATH).expect(200);
+    expect(middleware[0].called).to.be.true;
+    expect(middleware[1].called).to.be.true;
+  });
+
+  // AUTH JWT
+
+  it('it should authenticate with authJwt middleware', async () => {
+    const id = randomUUID();
+    const token = generateAccessToken(id);
+    const endpoint = new Endpoint({
+      ...config,
+      authType: EndpointAuthType.JWT,
+      handler: (req: Request, res: Response) => {
+        res.sendStatus(200);
+      }
+    } as EndpointOptions<EndpointAuthType.JWT>);
+    const server = new Server({ endpoints: [endpoint] });
+
+    await server.init();
+
+    await request(server.getApp())
+      .get(PATH)
+      .set('Authorization', 'Bearer ' + token)
+      .expect(200);
+
+    await server.shutdown();
+  });
+
+  // AUTH ADMIN
+
+  it('it should authenticate with authAdmin middleware', async () => {
+    const email = faker.internet.email();
+    const permission = faker.lorem.word();
+    const token = generateAccessToken(
+      email,
+      {
+        audience: [process.env.ADMIN_API_ACCESS_TOKEN_AUDIENCE as string],
+        issuer: process.env.ADMIN_ACCESS_TOKEN_ISSUER as string
+      },
+      { per: permission }
+    );
+    const endpoint = new Endpoint({
+      ...config,
+      authType: EndpointAuthType.ADMIN,
+      authParams: { permission },
+      handler: (req: Request, res: Response) => {
+        res.sendStatus(200);
+      }
+    } as EndpointOptions<EndpointAuthType.ADMIN>);
+
+    endpoint.register(app);
+    await request(app)
+      .get(PATH)
+      .set('Authorization', 'Bearer ' + token)
+      .expect(200);
+  });
+
+  it('it should authenticate with authAdmin middleware and check permission', async () => {
+    const email = faker.internet.email();
+    const permission = faker.lorem.word();
+    const token = generateAccessToken(
+      email,
+      {
+        audience: [process.env.ADMIN_API_ACCESS_TOKEN_AUDIENCE as string],
+        issuer: process.env.ADMIN_ACCESS_TOKEN_ISSUER as string
+      },
+      { per: permission }
+    );
+
+    const endpoint = new Endpoint({
+      ...config,
+      authType: EndpointAuthType.ADMIN,
+      authParams: { permission },
+      handler: (req: Request, res: Response) => {
+        res.sendStatus(200);
+      }
+    } as EndpointOptions<EndpointAuthType.ADMIN>);
+
+    endpoint.register(app);
+    await request(app)
+      .get(PATH)
+      .set('Authorization', 'Bearer ' + token)
+      .expect(200);
+  });
+
+  it('it should authenticate with authAdmin middleware and check permissions', async () => {
+    const email = faker.internet.email();
+    const permissions = [
+      faker.lorem.word(),
+      faker.lorem.word(),
+      faker.lorem.word()
+    ];
+    const token = generateAccessToken(
+      email,
+      {
+        audience: [process.env.ADMIN_API_ACCESS_TOKEN_AUDIENCE as string],
+        issuer: process.env.ADMIN_ACCESS_TOKEN_ISSUER as string
+      },
+      { per: permissions }
+    );
+
+    const endpoint = new Endpoint({
+      ...config,
+      authType: EndpointAuthType.ADMIN,
+      authParams: { permission: permissions[1] },
+      handler: (req: Request, res: Response) => {
+        res.sendStatus(200);
+      }
+    } as EndpointOptions<EndpointAuthType.ADMIN>);
+
+    endpoint.register(app);
+    await request(app)
+      .get(PATH)
+      .set('Authorization', 'Bearer ' + token)
+      .expect(200);
+  });
+
+  it('it should reject if the user has no valid JWT', async () => {
+    const endpoint = new Endpoint({
+      ...config,
+      authType: EndpointAuthType.JWT,
+      handler: (req: Request, res: Response) => {
+        res.sendStatus(200);
+      }
+    } as EndpointOptions<EndpointAuthType.JWT>);
+    endpoint.register(app);
+    await request(app).get(PATH).expect(401);
+  });
+
+  it('it should not trigger JWT error if acceptInvalid is set', async () => {
+    const endpoint = new Endpoint({
+      ...config,
+      authType: EndpointAuthType.JWT,
+      authParams: { acceptInvalid: true },
+      handler: (req: Request, res: Response) => {
+        res.sendStatus(200);
+      }
+    } as EndpointOptions<EndpointAuthType.JWT>);
+    endpoint.register(app);
+    await request(app).get(PATH).expect(200);
+  });
+
+  // TLS
+  it('it should authenticate with authTLS middleware', async () => {
+    const endpoint = new Endpoint({
+      ...config,
+      authType: EndpointAuthType.TLS,
+      handler: (req: Request, res: Response) => {
+        res.sendStatus(200);
+      }
+    } as EndpointOptions<EndpointAuthType.TLS>);
+    const server = new Server({ endpoints: [endpoint] });
+
+    await server.init();
+
+    await expect(
+      tlsRequest({
+        method: 'get',
+        url: `https://127.0.0.1:${process.env.PORT as string}${PATH}`
+      })
+    ).to.not.be.rejected;
+
+    await server.shutdown();
+  });
+
+  it('it should reject if the user has no valid TLS credentials', async () => {
+    const endpoint = new Endpoint({
+      ...config,
+      authType: EndpointAuthType.TLS,
+      handler: (req: Request, res: Response) => {
+        res.sendStatus(200);
+      }
+    } as EndpointOptions<EndpointAuthType.TLS>);
+    const server = new Server({ endpoints: [endpoint] });
+
+    await server.init();
+
+    await expect(
+      httpRequest({
+        method: 'get',
+        url: `https://127.0.0.1:${process.env.PORT as string}${PATH}`
+      })
+    ).to.be.rejected;
+
+    await server.shutdown();
+  });
+});

package/src/entities/Endpoint/Endpoint.ts

@@ -0,0 +1,202 @@
+import {
+  RequestHandler,
+  ErrorRequestHandler,
+  Application,
+  Request,
+  Response,
+  NextFunction
+} from 'express';
+import { Schema } from 'express-validator';
+import { EngineError } from '../EngineError';
+import {
+  EndpointOptions,
+  EndpointAuthType,
+  EndpointAuthTypes,
+  EndpointMethod,
+  EndpointMethods,
+  EndpointAuthParams,
+  Middleware,
+  MiddlewareChainElement,
+  SafeMiddleWareChain,
+  EndpointAuthHandlers,
+  EndpointAuthHandler,
+  EndpointRequestType,
+  EndpointHandler
+} from './Endpoint.types';
+import { LogSeverity } from 'const';
+import { validate, fileUploader, requestMetrics } from 'middleware';
+import { FileUploaderConfig } from 'middleware/fileUploader';
+import { reportDebug, reportError, reportInfo } from 'utils/report';
+
+const namespace = 'engine:Endpoint';
+
+/**
+ * Object representing a REST endpoint served by server
+ */
+export class Endpoint<T extends EndpointAuthType> {
+  /** Path at which the endpoint is reachable */
+  public readonly path: string;
+  /** HTTP method of the endpoint */
+  public readonly method: EndpointMethod;
+  /** Authentication system required by this endpoint */
+  public readonly authType: T;
+  /** Function handling the endpoint's business logic */
+  private handler: EndpointHandler<T>;
+  /** Validation schema that the request must pass before reaching the handler */
+  private validator: Schema;
+  /** Authentication related options for this endpoint */
+  private authParams?: EndpointAuthParams<T>;
+  /** Settings to upload files through this endpoint (this will automatically switch the expected request to be a multipart) */
+  private files?: Array<FileUploaderConfig>;
+  /** Express request handlers that should run on this endpoint before the business logic, they will run after the global middleware */
+  private middleware?: Array<Middleware<T>>;
+  /** Express error handlers that should be registered for this endpoint. they will run before the global error handler */
+  private errorMiddleware?: Array<ErrorRequestHandler>;
+
+  /** Create a REST endpoint */
+  public constructor(config: EndpointOptions<T>) {
+    reportDebug({
+      namespace,
+      message: `Creating Endpoint [${config.method} - ${config.path}]`,
+      data: {
+        method: config.method,
+        path: config.path,
+        authType: config.authType,
+        authParams: config.authParams,
+        file: config.file
+      }
+    });
+
+    if (typeof config.path !== 'string')
+      throw new EngineError({
+        message: 'Endpoint path was not declared as a string'
+      });
+    this.path = config.path;
+
+    if (!EndpointMethods.includes(config.method))
+      throw new EngineError({
+        message: 'Endpoint method is not a valid HTTP method'
+      });
+    this.method = config.method;
+
+    if (typeof config.handler !== 'function')
+      throw new EngineError({ message: 'Endpoint handler is not a function' });
+    this.handler = config.handler;
+
+    if (!EndpointAuthTypes.includes(config.authType))
+      throw new EngineError({ message: 'Endpoint auth type is not valid' });
+    this.authType = config.authType;
+
+    this.validator = config.validator;
+    this.authParams = config.authParams;
+    this.files = config.file ? [config.file] : config.files;
+
+    // Middleware can both be function or arrays
+    if (typeof config.middleware === 'function')
+      this.middleware = [config.middleware];
+    if (config.middleware instanceof Array) this.middleware = config.middleware;
+    if (typeof config.errorMiddleware === 'function')
+      this.errorMiddleware = [config.errorMiddleware];
+    if (config.errorMiddleware instanceof Array)
+      this.errorMiddleware = config.errorMiddleware;
+  }
+
+  /**
+   * Register the endpoint to a react app
+   */
+  public register(app: Application): void {
+    // First initialize the handling calculation
+    const middlewareChain: Array<MiddlewareChainElement<T>> = [requestMetrics];
+    // Register auth middleware
+    middlewareChain.push(...this.getAuthMiddleware(this.authType));
+    if (this.files) {
+      // Register file upload
+      // Validation is included in the file upload process as this uses multipart/form-data
+      middlewareChain.push(fileUploader(this.files, this.validator));
+    } else {
+      // Register validator for regular cases
+      middlewareChain.push(validate(this.validator));
+    }
+    // Register additional middleware
+    if (this.middleware) {
+      middlewareChain.push(...this.middleware);
+    }
+    // Register handler
+    middlewareChain.push(this.handler);
+    // Wrap middleware to await any async execution and catch any errors thrown
+    const safeMiddlewareChain: SafeMiddleWareChain =
+      this.catchExceptionForExpress(middlewareChain);
+    // Register error middleware
+    if (this.errorMiddleware) {
+      safeMiddlewareChain.push(...this.errorMiddleware);
+    }
+    app[this.method](
+      this.path,
+      ...(safeMiddlewareChain.flat() as Array<
+        RequestHandler | ErrorRequestHandler
+      >)
+    );
+  }
+
+  /**
+   * Catch exceptions thrown inside of middleware and pass them properly to express
+   */
+  private catchExceptionForExpress(
+    middlewareChain: Array<MiddlewareChainElement<T>>
+  ): SafeMiddleWareChain {
+    return middlewareChain.map((middleware) => {
+      if (middleware instanceof Array) {
+        return this.catchExceptionForExpress(middleware);
+      }
+      if (typeof middleware === 'function') {
+        return (req: Request, res: Response, next: NextFunction) => {
+          (async (): Promise<void> => {
+            try {
+              await middleware(req as EndpointRequestType[T], res, next);
+            } catch (err) {
+              next(err);
+            }
+          })().catch((error) => {
+            reportError(error);
+          });
+        };
+      }
+      throw new EngineError({
+        message: 'Middleware is not a function nor an array',
+        data: { type: typeof middleware }
+      });
+    });
+  }
+
+  /**
+   * Get the authentication middleware for a given type of authentication
+   */
+  private getAuthMiddleware(authType: EndpointAuthType): Array<RequestHandler> {
+    const middlewareChain: Array<RequestHandler> = [];
+
+    const handler = EndpointAuthHandlers[authType] as EndpointAuthHandler<T>;
+    if (!handler) {
+      reportInfo({
+        severity: LogSeverity.WARNING,
+        message: `Endpoint "${this.method} - ${this.path}" was declared with no authentication method`
+      });
+      return [];
+    }
+
+    const middleware = handler(this.authParams);
+
+    middlewareChain.push(
+      async (request: Request, response: Response, next: NextFunction) => {
+        try {
+          await middleware(request, response, next);
+        } catch (error) {
+          if (!this.authParams?.acceptInvalid) throw error;
+          reportError(error);
+          next();
+        }
+      }
+    );
+
+    return middlewareChain;
+  }
+}