node-server-engine 1.0.5

package/src/utils/report/output.types.ts

@@ -0,0 +1,70 @@
+import { LogSeverity } from 'const';
+
+/** Structure of the request reporting in log entries */
+interface LogEntryRequest {
+  /** Requested URL */
+  url: string;
+  /** HTTP method used */
+  method: string;
+  /** Referer website */
+  referrer?: string;
+  /** User-Agent of the connected client */
+  userAgent?: string;
+  /** IP address of the client */
+  remoteIp: string | undefined;
+  /** HTTP status code returned to the client */
+  responseStatusCode?: number;
+}
+
+/** Structure of the context entry in log entries */
+interface LogEntryContext {
+  /** User that made a request */
+  user?: string;
+  /** Info on the processed HTTP request */
+  httpRequest?: LogEntryRequest;
+}
+
+/** Structure of a log entry */
+export interface LogEntry {
+  /** Severity level at which the entry should be logged */
+  severity: LogSeverity;
+  /** Type of error */
+  errorType?: string;
+  /** Human readable error message that will be logged */
+  message: string;
+  /** Stack-trace of the error */
+
+  stack_trace?: string;
+  /** Additional data that accompanies the error in the logs */
+  data?: unknown;
+  /** Machine readable error code that is returned to the client */
+  errorCode?: string;
+  /** HTTP status code that is returned to the client */
+  statusCode?: number;
+  /** GCP error type */
+  '@type'?: string;
+  /** Error context */
+  context?: LogEntryContext;
+}
+
+/** Stricture of a log entry context entry */
+interface LogEntryServiceContext {
+  /** Name of the service in which the error ocurred */
+  service?: string;
+  /** Version of the service in which the error ocurred */
+  version?: string;
+  /** Environment in which the error ocurred (dev/staging/prod) */
+  environment?: string;
+  /** ID of the instance that got the error */
+  instance?: string;
+}
+
+/** Complete log entry with call-stack */
+export interface FullLogEntry extends LogEntry {
+  /** Line at which the error was thrown */
+  lineNumber: number;
+  /** Name of the file in which the error was thrown */
+  fileName: string;
+  /** Context of the error */
+  serviceContext: LogEntryServiceContext;
+}

package/src/utils/report/report.test.ts

@@ -0,0 +1,133 @@
+import { expect } from 'chai';
+import { faker } from '@faker-js/faker';
+import { describe, it, beforeEach } from 'mocha';
+import { stub, match } from 'sinon';
+import * as output from './output';
+import { reportInfo, reportDebug, resetNamespaceSelector } from './report';
+import { InfoLogEntry } from './report.types';
+
+describe('Utils - Report', () => {
+  it('should collect filename and line number', () => {
+    let result = reportInfo('example');
+    expect(result.fileName).to.equal(
+      `${__dirname}/report.test.ts`.replace(/.*src\//, 'src/')
+    );
+    expect(result.severity).to.equal('INFO');
+    expect(result.message).to.equal('example');
+
+    const data: InfoLogEntry = { message: 'world' };
+    result = reportInfo(data);
+    expect(result.message).to.equal('world');
+    expect(result.fileName).to.equal(
+      `${__dirname}/report.test.ts`.replace(/.*src\//, 'src/')
+    );
+  });
+
+  describe('Report Debug', () => {
+    let globalNamespace: string;
+
+    beforeEach(() => {
+      resetNamespaceSelector();
+
+      globalNamespace = faker.lorem.slug();
+      reportDebug.setNameSpace(globalNamespace);
+    });
+
+    afterEach(() => {
+      reportDebug.clearNamespace();
+    });
+
+    it('should report when the namespace is specified', () => {
+      const namespace = faker.lorem.word();
+      process.env.DEBUG = globalNamespace + ':' + namespace;
+      const outputStub = stub(output, 'output');
+      const message = faker.lorem.sentence();
+      reportDebug({ message, namespace });
+      expect(outputStub).to.have.been.calledOnceWithExactly(
+        match({
+          message: `[${namespace}] ${message}`,
+          severity: 'DEBUG',
+          namespace: namespace
+        })
+      );
+    });
+
+    it('should report when the namespace is specified with a wildcard', () => {
+      const namespace = faker.lorem.word();
+      process.env.DEBUG = globalNamespace + ':' + `${namespace}:*`;
+      const outputStub = stub(output, 'output');
+      const message = faker.lorem.sentence();
+      const prefix = faker.lorem.word();
+      const actualNamespace = `${namespace}:${prefix}`;
+      reportDebug({ message, namespace: actualNamespace });
+      expect(outputStub).to.have.been.calledOnceWithExactly(
+        match({
+          message: `[${prefix}] ${message}`,
+          severity: 'DEBUG',
+          namespace: actualNamespace
+        })
+      );
+    });
+
+    it('should report when multiple namespaces are specified', () => {
+      const namespace = faker.lorem.word();
+      process.env.DEBUG =
+        globalNamespace +
+        ':' +
+        `${namespace},${faker.lorem.word()},${faker.lorem.word()}`;
+      const outputStub = stub(output, 'output');
+      const message = faker.lorem.sentence();
+      reportDebug({ message, namespace });
+      expect(outputStub).to.have.been.calledOnceWithExactly(
+        match({
+          message: `[${namespace}] ${message}`,
+          severity: 'DEBUG',
+          namespace: namespace
+        })
+      );
+    });
+
+    it('should not report when another namespace is specified', () => {
+      process.env.DEBUG = faker.lorem.word();
+      const outputStub = stub(output, 'output');
+      reportDebug({
+        message: faker.lorem.sentence(),
+        namespace: faker.lorem.word()
+      });
+      expect(outputStub).to.not.have.been.called;
+    });
+
+    it('should ignore the global namespace in server engine report debug', () => {
+      const namespace = 'engine';
+      process.env.DEBUG = `${namespace}:*`;
+      const prefix = faker.lorem.word();
+      const actualNamespace = `${namespace}:${prefix}`;
+      const outputStub = stub(output, 'output');
+      const message = faker.lorem.sentence();
+      reportDebug({ message, namespace: actualNamespace });
+      expect(outputStub).to.have.been.calledOnceWithExactly(
+        match({
+          message: `[${prefix}] ${message}`,
+          severity: 'DEBUG',
+          namespace: actualNamespace
+        })
+      );
+    });
+
+    it('should report with no global namespace', () => {
+      reportDebug.clearNamespace();
+      const namespace = faker.lorem.word();
+      process.env.DEBUG = namespace;
+      const outputStub = stub(output, 'output');
+      const message = faker.lorem.sentence();
+      reportDebug({ message, namespace });
+      expect(outputStub).to.have.been.calledOnceWithExactly(
+        match({
+          message: `[${namespace}] ${message}`,
+          severity: 'DEBUG',
+          namespace
+        })
+      );
+    });
+  });
+});

package/src/utils/report/report.ts

@@ -0,0 +1,134 @@
+import { Request } from 'express';
+import { output } from './output';
+import { LogEntry, FullLogEntry } from './output.types';
+import { DebugLogEntry, InfoLogEntry } from './report.types';
+import { LogSeverity } from 'const';
+import { EngineError } from 'entities/EngineError';
+import { WebError } from 'entities/WebError';
+import {} from 'middleware/authHmac/authHmac.types';
+import {} from 'middleware/authJwt/authJwt.types';
+import {} from 'middleware/authTls/authTls.types';
+import {} from 'middleware/authAdmin/authAdmin.types';
+
+/** Default generic logger */
+export function reportInfo(data: InfoLogEntry | string): FullLogEntry {
+  return output({
+    severity: LogSeverity.INFO,
+    ...(typeof data === 'string' ? { message: data } : data)
+  });
+}
+
+/** Error specific logger */
+export function reportError(
+  error: unknown | Error | EngineError | WebError,
+  request?: Request
+): FullLogEntry {
+  let logEntry: LogEntry =
+    error instanceof Error
+      ? {
+          message: error.message,
+          stack_trace: error.stack,
+          severity: LogSeverity.ERROR
+        }
+      : {
+          message: 'An unknown error occurred',
+          data: error,
+          severity: LogSeverity.CRITICAL
+        };
+
+  if (error instanceof EngineError) {
+    logEntry = {
+      ...logEntry,
+      severity: error.severity,
+      errorType: error.constructor.name,
+      data: error.data,
+      '@type':
+        !(error instanceof WebError) || error.statusCode >= 500
+          ? 'type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent'
+          : undefined
+    };
+  }
+
+  if (error instanceof WebError) {
+    logEntry = {
+      ...logEntry,
+      errorCode: error.errorCode,
+      statusCode: error.statusCode
+    };
+  }
+
+  if (request) {
+    logEntry = {
+      ...logEntry,
+      context: {
+        user:
+          request.user?.id ?? request.hosts?.join(',') ?? request.admin?.email,
+        httpRequest: {
+          url: request.originalUrl,
+          method: request.method,
+          referrer: request.header('Referer'),
+          userAgent: request.header('User-Agent'),
+          remoteIp: request.ip,
+          responseStatusCode:
+            error instanceof WebError ? error.statusCode : undefined
+        }
+      }
+    };
+  }
+
+  return output(logEntry);
+}
+
+export let NAMESPACE_SELECTORS: undefined | Array<RegExp>;
+
+/** Generate the namespace selectors based on the debug variable */
+function initNamespaceSelector(): void {
+  if (process.env.DEBUG)
+    NAMESPACE_SELECTORS = process.env.DEBUG.split(',').map(
+      (namespace) => new RegExp('^' + namespace.replace(/\*/g, '.*?') + '$')
+    );
+}
+
+/** Reset the namespace selectors */
+export function resetNamespaceSelector(): void {
+  NAMESPACE_SELECTORS = undefined;
+}
+
+let debugNamespace: string | undefined;
+
+/** Log a message for debugging purpose, based on a namespace specified in an environment variable */
+export function reportDebug(data: DebugLogEntry): FullLogEntry | undefined {
+  if (!NAMESPACE_SELECTORS) initNamespaceSelector();
+  let { namespace } = data;
+  const isEngineReport = namespace ? namespace.startsWith('engine') : false;
+
+  if (debugNamespace && !isEngineReport) {
+    namespace = debugNamespace + ':' + namespace;
+  }
+
+  const match =
+    namespace &&
+    NAMESPACE_SELECTORS &&
+    NAMESPACE_SELECTORS.some((selector) => selector.test(namespace));
+  if (!match) return;
+
+  // Generate a prefix with the right most part of the namespace
+  const spaces = namespace.split(':');
+  const prefix = spaces[spaces.length - 1];
+
+  return output({
+    severity: LogSeverity.DEBUG,
+    ...data,
+    message: `[${prefix}] ${data.message}`
+  });
+}
+
+/** Specify a global debugging namespace */
+reportDebug.setNameSpace = function (globalNamespace: string): void {
+  debugNamespace = globalNamespace;
+};
+
+/** Remove any defined global namespace */
+reportDebug.clearNamespace = function (): void {
+  debugNamespace = undefined;
+};

package/src/utils/report/report.types.ts

@@ -0,0 +1,13 @@
+import { LogEntry } from './output.types';
+import { LogSeverity } from 'const';
+
+/** Structure of debug logs */
+export interface DebugLogEntry extends Omit<LogEntry, 'severity'> {
+  /** Debugging namespace in which the entry is */
+  namespace: string;
+}
+
+export type InfoLogEntry = Omit<LogEntry, 'severity'> & {
+  /** Severity level of the entries */
+  severity?: LogSeverity;
+};

package/src/utils/request/index.ts

@@ -0,0 +1 @@
+export * from './request';

package/src/utils/request/request.test.ts

@@ -0,0 +1,26 @@
+import { expect } from 'chai';
+import { faker } from '@faker-js/faker';
+import nock, { cleanAll } from 'nock';
+import { request } from './request';
+import { EngineError } from 'entities/EngineError';
+
+describe('Utils - Request', function () {
+  afterEach(() => {
+    cleanAll();
+  });
+
+  it('should retry a request 5 times if network errors happen', async () => {
+    const url = faker.internet.url();
+
+    const scope = nock(url)
+      .get('/')
+      .times(5)
+      .replyWithError({ code: 'ECONNREFUSED' });
+
+    const promise = request({ url });
+
+    await expect(promise).to.eventually.be.rejectedWith(EngineError);
+
+    scope.isDone();
+  });
+});

package/src/utils/request/request.ts

@@ -0,0 +1,48 @@
+import axios, { AxiosResponse, AxiosRequestConfig } from 'axios';
+import { LogSeverity } from 'const';
+import { EngineError, EngineErrorOptions } from 'entities/EngineError';
+
+/** Make a http(s) request through axios with proper error handling */
+export async function request<T = unknown>(
+  options: AxiosRequestConfig,
+  tryCount = 1
+): Promise<AxiosResponse<T>> {
+  try {
+    return await axios.request<T, AxiosResponse<T>>(options);
+  } catch (error: unknown) {
+    // In case of networking error, we attempt to retry the connection if we did less than 5 attempts
+    if (
+      tryCount < 5 &&
+      axios.isAxiosError(error) &&
+      error.code &&
+      ['ECONNABORTED', 'ECONNREFUSED', 'ECONNRESET', 'EAI_AGAIN'].includes(
+        error.code
+      )
+    ) {
+      return request<T>(options, tryCount + 1);
+    }
+    const errorOptions: EngineErrorOptions = {
+      message:
+        error instanceof Error
+          ? error.message
+          : typeof error === 'string'
+            ? error
+            : 'An unknown error occurred',
+      severity: LogSeverity.CRITICAL,
+      data: { error }
+    };
+    if (error instanceof Error) {
+      errorOptions.message = error.message;
+      errorOptions.error = error;
+    }
+    // A response was returned but it was not a 200
+    if (axios.isAxiosError(error) && error.response) {
+      errorOptions.data = {
+        data: error.response.data as unknown,
+        status: error.response.status,
+        headers: error.response.headers as unknown
+      };
+    }
+    throw new EngineError(errorOptions);
+  }
+}

package/src/utils/semverCompare/index.ts

@@ -0,0 +1 @@
+export * from './semverCompare';

package/src/utils/semverCompare/semverCompare.test.ts

@@ -0,0 +1,49 @@
+import { expect } from 'chai';
+import { semverCompare } from './semverCompare';
+import { EngineError } from 'entities/EngineError';
+
+describe('Utils - SemVer Compare', function () {
+  it('Should throw an error if given a wrong formatted item', () => {
+    expect(() => semverCompare('1.0.0', 'test')).to.throw(EngineError);
+    expect(() => semverCompare('wrong', '1.0.0')).to.throw(EngineError);
+  });
+
+  it('Should compare majors', () => {
+    expect(semverCompare('1.0.0', '2.0.0')).to.equal(-1);
+    expect(semverCompare('2.0.0', '1.0.0')).to.equal(1);
+  });
+
+  it('Should compare minors', () => {
+    expect(semverCompare('1.1.0', '1.2.0')).to.equal(-1);
+    expect(semverCompare('2.5.0', '2.3.0')).to.equal(1);
+  });
+
+  it('Should compare patches', () => {
+    expect(semverCompare('1.1.1', '1.1.2')).to.equal(-1);
+    expect(semverCompare('2.5.6', '2.5.0')).to.equal(1);
+  });
+
+  it('Should compare patches', () => {
+    expect(semverCompare('1.1.1', '1.1.2')).to.equal(-1);
+    expect(semverCompare('2.5.6', '2.5.0')).to.equal(1);
+  });
+
+  it('Should compare releases types', () => {
+    expect(semverCompare('1.1.1-rc.1', '1.1.1')).to.equal(-1);
+    expect(semverCompare('1.1.1-beta.1', '1.1.1-rc.1')).to.equal(-1);
+    expect(semverCompare('1.1.1-alpha.1', '1.1.1-beta.1')).to.equal(-1);
+    expect(semverCompare('2.5.5', '2.5.5-rc.1')).to.equal(1);
+    expect(semverCompare('2.5.5-rc.1', '2.5.5-beta.1')).to.equal(1);
+    expect(semverCompare('2.5.5-beta.1', '2.5.5-alpha.1')).to.equal(1);
+  });
+
+  it('Should compare pre-release versions', () => {
+    expect(semverCompare('1.1.1-alpha.1', '1.1.1-alpha.2')).to.equal(-1);
+    expect(semverCompare('2.5.6-rc.5', '2.5.6-rc.3')).to.equal(1);
+  });
+
+  it('Should handle equality', () => {
+    expect(semverCompare('1.1.1', '1.1.1')).to.equal(0);
+    expect(semverCompare('2.5.6-rc.5', '2.5.6-rc.5')).to.equal(0);
+  });
+});

package/src/utils/semverCompare/semverCompare.ts

@@ -0,0 +1,60 @@
+import validator from 'validator';
+import { EngineError } from 'entities/EngineError';
+
+// Regex to validate our SemVer style and capture the different parts
+const SEMVER_REGEX =
+  /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:(alpha|beta|rc)(?:\.(0|[1-9]\d*))))?$/;
+
+/**
+ * Comparison function for our SemVer strings, includes support ofr pre-releases
+ * @param {string} v1
+ * @param {string} v2
+ * @return {number} - -1 if v1 < v2, 0 if v1 = v2, +1 if v1 > v2
+ */
+export function semverCompare(v1: string, v2: string): 1 | -1 | 0 {
+  const [match1, match2] = [v1, v2].map((v) => v.match(SEMVER_REGEX));
+  if (!match1 || !match2)
+    throw new EngineError({
+      message: 'Provided invalid SemVer string, can not compare',
+      data: { v1, v2 }
+    });
+  const [
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    [_1, major1, minor1, patch1, preType1, preVersion1],
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    [_2, major2, minor2, patch2, preType2, preVersion2]
+  ] = [match1, match2].map((group) =>
+    // We parse to int the parts that can be
+    group.map((item) => (item && validator.isInt(item) ? parseInt(item) : item))
+  );
+
+  // Compare majors first
+  if (major1 < major2) return -1;
+  if (major1 > major2) return 1;
+
+  // Compare minors second
+  if (minor1 < minor2) return -1;
+  if (minor1 > minor2) return 1;
+
+  // Compare patch third
+  if (patch1 < patch2) return -1;
+  if (patch1 > patch2) return 1;
+
+  // Compare pre-release type
+  // Release > pre-release
+  if (!preType1 && !preType2) return 0;
+  if (preType1 && !preType2) return -1;
+  if (!preType1 && preType2) return 1;
+
+  // RC > Beta > Alpha
+  if (preType1 !== 'rc' && preType2 === 'rc') return -1;
+  if (preType1 === 'rc' && preType2 !== 'rc') return 1;
+  if (preType1 !== 'beta' && preType2 === 'beta') return -1;
+  if (preType1 === 'beta' && preType2 !== 'beta') return 1;
+
+  // Finally compare the pre-release versions
+  if (preVersion1 < preVersion2) return -1;
+  if (preVersion1 > preVersion2) return 1;
+
+  return 0;
+}

package/src/utils/sendEmail/index.ts

@@ -0,0 +1 @@
+export * from './sendEmail';

package/src/utils/sendEmail/sendEmail.ts

@@ -0,0 +1,27 @@
+import { EmailRecipient } from './sendEmail.types';
+import { tlsRequest } from 'utils/tlsRequest';
+
+/**
+ * Send an email through the email service
+ * @param userId - ID of the user that should receive the email
+ * @param template - Email template to use
+ * @param translationKey - Key used to get localized strings
+ * @param parameters - Variables that can be inserted in the email template and localized strings
+ * @param tags - Data injected in the localized strings as HTML tags
+ * @param to - Users to which the email should be sent
+ */
+export async function sendEmail(
+  userId: string,
+  template: string,
+  translationKey: string,
+  parameters?: unknown,
+  tags?: unknown,
+  to?: Array<EmailRecipient>
+): Promise<unknown> {
+  return tlsRequest({
+    method: 'post',
+    url: '/send',
+    baseURL: process.env.EMAIL_SERVICE_URL,
+    data: { userId, template, translationKey, parameters, tags, to }
+  });
+}

package/src/utils/sendEmail/sendEmail.types.ts

@@ -0,0 +1,7 @@
+/** Structure representing an email recipient */
+export interface EmailRecipient {
+  /** Email of the person to which the email should be sent */
+  email: string;
+  /** Name of the person receiving the email */
+  name?: string;
+}

package/src/utils/sendPush/index.ts

@@ -0,0 +1,2 @@
+export * from './sendPush';
+export * from './sendPush.types';

package/src/utils/sendPush/sendPush.ts

@@ -0,0 +1,20 @@
+import { SendPushNotification } from './sendPush.types';
+import { tlsRequest } from 'utils/tlsRequest';
+
+/**
+ * Send a push notification through the push service
+ * @param userId - ID of the user that should receive the notification
+ * @param notification - Notification that should be sent
+ * @return Push service response
+ */
+export async function sendPush(
+  userId: string,
+  notification: SendPushNotification
+): Promise<unknown> {
+  return tlsRequest({
+    method: 'post',
+    url: '/push',
+    baseURL: process.env.PUSH_SERVICE_URL,
+    data: { userId, ...notification }
+  });
+}

package/src/utils/sendPush/sendPush.types.ts

@@ -0,0 +1,25 @@
+/** Stricture representing a push notification to send */
+export interface SendPushNotification {
+  /** Title of the notification */
+  title?: string;
+  /** Body of the notification */
+  body?: string;
+  /** Data payload of the notification */
+  payload?: unknown;
+  /** Indicates that the notification is a VOIP notification */
+  voip?: boolean;
+  /** Indicate that it is a background notification (data only, low priority) */
+  background?: boolean;
+  /** Push token can be specified here is we want to send to a given user */
+  token?: string;
+  /** Indicates that the data content can be mutated by the client (iOS) */
+  mutable?: boolean;
+  /** Indicates that the notification requires some client side processing to be displayed (iOS) */
+  contentAvailable?: boolean;
+  /** Time to live of the notification in seconds. After this the notification will not be distributed */
+  ttl?: number;
+  /** Indicate that it is a high priority notification */
+  priority?: boolean;
+  /** Notifications with the same string here will be collapsed in the system tray */
+  collapseId?: string;
+}

package/src/utils/tlsConfig/index.ts

@@ -0,0 +1,2 @@
+export * from './tlsConfig';
+export * from './tlsConfig.types';

package/src/utils/tlsConfig/tlsConfig.test.ts

@@ -0,0 +1,32 @@
+import path from 'path';
+import { expect } from 'chai';
+import { validateTlsConfig } from './tlsConfig.validate';
+
+describe('utils - TLS Config', () => {
+  beforeEach(() => {
+    delete process.env.TLS_REQUEST_KEY;
+    delete process.env.TLS_REQUEST_CERT;
+    delete process.env.TLS_REQUEST_CA;
+    delete process.env.TLS_SERVER_KEY;
+    delete process.env.TLS_SERVER_CERT;
+    delete process.env.TLS_CA;
+  });
+
+  it('should accept Request TLS environment variables', () => {
+    process.env.TLS_REQUEST_KEY = path.resolve('certs/client.key');
+    process.env.TLS_REQUEST_CERT = path.resolve('certs/client.crt');
+    process.env.TLS_REQUEST_CA = path.resolve('certs/ca.crt');
+    expect(validateTlsConfig).to.throw;
+  });
+
+  it('should accept Server TLS environment variables', () => {
+    process.env.TLS_SERVER_KEY = path.resolve('certs/server.key');
+    process.env.TLS_SERVER_CERT = path.resolve('certs/server.crt');
+    process.env.TLS_CA = path.resolve('certs/ca.crt');
+    expect(validateTlsConfig).to.throw;
+  });
+
+  it('should throw an EngineError if no environment setting', () => {
+    expect(validateTlsConfig).to.throw;
+  });
+});