node-server-engine 1.0.5

package/src/entities/Localizator/Localizator.ts

@@ -0,0 +1,139 @@
+import { guessNamingConvention } from './guessNamingConvention';
+import {
+  LocalizatorLocalizationData,
+  LocalizatorLocalizationDataElement,
+  LocalizatorScripts,
+  LocalizatorNamingConventions
+} from './Localizator.types';
+import { EngineError } from 'entities/EngineError';
+import { LifecycleController } from 'entities/LifecycleController';
+import { Storage } from 'entities/Storage';
+import { checkEnvironment } from 'utils/checkEnvironment';
+import { envAssert } from 'utils/envAssert';
+import { reportError, reportDebug } from 'utils/report';
+
+const namespace = 'engine:localizator';
+
+const REFRESH_FREQUENCY = 10 * 60 * 1000;
+
+let localeData: undefined | LocalizatorLocalizationData;
+let scripts: undefined | LocalizatorScripts;
+let interval: NodeJS.Timeout | string | number | undefined;
+
+/** Service handling contextual localization */
+export const Localizator = {
+  async init(): Promise<void> {
+    checkEnvironment({ LOCALES_BUCKET: envAssert.isString() });
+    await Localizator.synchronize();
+    // Keep synchronizing
+    interval = setInterval(() => {
+      Localizator.synchronize().catch((error) => {
+        reportError(error);
+      });
+    }, REFRESH_FREQUENCY);
+    LifecycleController.register(Localizator);
+  },
+
+  /**
+   * Fetch a JSON file from the locales bucket
+   */
+  async getLocaleFile<T>(file: string): Promise<T> {
+    reportDebug({
+      namespace,
+      message: `Starting download of localization file [${file}]`,
+      data: { bucket: process.env.LOCALES_BUCKET, file }
+    });
+    const { data } = await Storage.get(
+      process.env.LOCALES_BUCKET as string,
+      file
+    );
+    const stringified = data.toString('utf-8');
+    const result = JSON.parse(stringified) as T;
+    reportDebug({
+      namespace,
+      message: `Fetched localization file [${file}]`,
+      data: { bucket: process.env.LOCALES_BUCKET, file, result }
+    });
+    return result;
+  },
+
+  /**
+   * Synchronizes the localeData and scripts files
+   * Should be called only once on startup
+   */
+  async synchronize(): Promise<void> {
+    reportDebug({ namespace, message: `Starting synchronizing` });
+    const [fetchedLocaleData, fetchedScripts] = await Promise.all([
+      Localizator.getLocaleFile<LocalizatorLocalizationData>('localeData.json'),
+      Localizator.getLocaleFile<LocalizatorScripts>('scripts.json')
+    ]);
+    localeData = fetchedLocaleData;
+    scripts = Localizator.buildRangeRegex(fetchedScripts);
+    reportDebug({ namespace, message: `Finished synchronizing` });
+  },
+
+  /** Transform unicode ranges in scripts data to regex */
+  buildRangeRegex(script: LocalizatorScripts): LocalizatorScripts {
+    for (const i of Object.keys(script)) {
+      const ranges = script[i].ranges;
+      if (ranges) {
+        script[i].rangeRegex = new RegExp(`[${ranges.join('')}]`, 'u');
+      }
+    }
+    return script;
+  },
+
+  /** Guess the naming convention to use for a given name and locale */
+  guessNamingConvention(
+    firstName: string,
+    lastName: string,
+    locale: string
+  ): LocalizatorNamingConventions {
+    if (!scripts || !localeData)
+      throw new EngineError({ message: 'Localizator is not initialized' });
+    const name = firstName + lastName; // merge two names if possible
+    return guessNamingConvention(scripts, localeData, name, locale);
+  },
+
+  /**
+   * Calculate the different display names for a user
+   */
+  getDisplayNames(
+    firstName: string,
+    lastName: string,
+    locale: string
+  ): LocalizatorNamingConventions {
+    const convention = Localizator.guessNamingConvention(
+      firstName,
+      lastName,
+      locale
+    );
+    return Object.keys(convention).reduce((convention, type) => {
+      const safeType = type as keyof LocalizatorNamingConventions;
+      convention[safeType] = convention[safeType]
+        .replace('{firstName}', firstName)
+        .replace('{lastName}', lastName ?? '')
+        .trim();
+      return convention;
+    }, convention);
+  },
+
+  /** Get the localization data for a locale */
+  getLocaleData(locale: string): LocalizatorLocalizationDataElement {
+    if (!localeData)
+      throw new EngineError({ message: 'Localizator is not initialized' });
+    return localeData[locale];
+  },
+
+  /** Check if a locale exists */
+  isValidLocale(locale: string): boolean {
+    if (!localeData)
+      throw new EngineError({ message: 'Localizator is not initialized' });
+    return localeData[locale] !== undefined;
+  },
+
+  /** Cleanup the instance */
+  shutdown(): void {
+    if (interval) clearTimeout(interval);
+  }
+};

package/src/entities/Localizator/Localizator.types.ts

@@ -0,0 +1,52 @@
+/** Defines how a name should be displayed for a locale in diferent context */
+export interface LocalizatorNamingConventions {
+  /** How the name is displayed in a common way */
+  regular: string;
+  /** How the name is displayed in a formal way */
+  formal: string;
+  /** How the name is displayed in a casual way */
+  casual: string;
+}
+
+/** Localization data for each of the locales  */
+export interface LocalizatorLocalizationData {
+  [locale: string]: LocalizatorLocalizationDataElement;
+}
+
+/** Describes localization settings for a locale */
+export interface LocalizatorLocalizationDataElement {
+  /** Is this locale available to the public */
+  enabled: boolean;
+  /** How this locale is displayed to the user */
+  display: string;
+  /** Configuration on how to display names in that locale */
+  names: {
+    /** Should the first name or the last name be displayed first */
+    firstNameFirst: boolean;
+    /** Is there a space between the two parts of the name */
+    spacing: boolean;
+    /** In case the user's name is not displayed in this language's script, how should it be displayed */
+    fallback?: LocalizatorNamingConventions;
+  };
+  /** Script used to identify text written in that language */
+  script?: string;
+  /** Key in google translation to identify that language */
+  cloudTranslationKey: string;
+  /** Unicode CLDR key to identify that language if it is different from the locale */
+  unicode?: string;
+}
+
+/** Script config data indexed by the script id */
+export interface LocalizatorScripts {
+  [script: string]: LocalizatorScript;
+}
+
+/** Localization config for a script */
+export interface LocalizatorScript {
+  /** Unicode range used to detect the script */
+  ranges: Array<string>;
+  /** How names are displayed when written in the script */
+  names: LocalizatorNamingConventions;
+  /** Regex added by the Localizator, used to match with the script unicode ranges */
+  rangeRegex?: RegExp;
+}

package/src/entities/Localizator/guessNamingConvention/guessNamingConvention.test.ts

@@ -0,0 +1,165 @@
+import { expect } from 'chai';
+import { faker } from '@faker-js/faker';
+import {
+  LocalizatorScript,
+  LocalizatorLocalizationDataElement
+} from '../Localizator.types';
+import {
+  guessNamingConvention,
+  DEFAULT_NAMING_CONVENTION
+} from './guessNamingConvention';
+
+/** Generate fake script config */
+function generateScriptData(
+  overrides: Partial<LocalizatorScript> = {}
+): LocalizatorScript {
+  return {
+    rangeRegex: new RegExp(`^\b$`, 'u'),
+    ranges: ['a'],
+    names: {
+      casual: faker.lorem.slug(),
+      regular: faker.lorem.slug(),
+      formal: faker.lorem.slug()
+    },
+    ...overrides
+  };
+}
+
+/** Generate locales file random data */
+function generateLocalizationData(
+  overrides: Partial<LocalizatorLocalizationDataElement> = {}
+): LocalizatorLocalizationDataElement {
+  return {
+    script: faker.lorem.word(),
+    enabled: true,
+    display: faker.lorem.word(),
+    names: {
+      firstNameFirst: true,
+      spacing: true
+    },
+    cloudTranslationKey: faker.location.countryCode(),
+    ...overrides
+  };
+}
+
+describe('Service - Localizator - Guess naming convention', function () {
+  it('should return the convention for the locale specifc script', function () {
+    const locale = faker.location.country();
+    const userScript = faker.lorem.word();
+    const name = faker.lorem.word();
+    const scriptData = generateScriptData({
+      rangeRegex: new RegExp(name, 'u')
+    });
+
+    const Localizator = {
+      localeData: {
+        [faker.location.countryCode()]: generateLocalizationData(),
+        [locale]: generateLocalizationData({ script: userScript })
+      },
+      scripts: {
+        [faker.lorem.word()]: generateScriptData(),
+        [userScript]: scriptData
+      }
+    };
+    const result = guessNamingConvention(
+      Localizator.scripts,
+      Localizator.localeData,
+      name,
+      locale
+    );
+
+    expect(result).to.equal(scriptData.names);
+  });
+
+  it('should return the convention for the the script detected in the name if no match wirth the default script', function () {
+    const locale = faker.location.country();
+    const expectedResult = {
+      casual: faker.lorem.word(),
+      regular: faker.lorem.word(),
+      formal: faker.lorem.word()
+    };
+    const userScript = faker.lorem.word();
+    const name = faker.lorem.word();
+    const Localizator = {
+      localeData: {
+        [faker.location.countryCode()]: generateLocalizationData(),
+        [locale]: generateLocalizationData({ script: userScript })
+      },
+      scripts: {
+        [faker.lorem.word()]: generateScriptData(),
+        [userScript]: generateScriptData(),
+        [faker.lorem.word()]: generateScriptData({
+          rangeRegex: new RegExp(name, 'u'),
+          names: expectedResult
+        })
+      }
+    };
+    const result = guessNamingConvention(
+      Localizator.scripts,
+      Localizator.localeData,
+      name,
+      locale
+    );
+    expect(result).to.equal(expectedResult);
+  });
+
+  it('should return the convention for the locale if no script match', function () {
+    const locale = faker.location.country();
+    const expectedResult = {
+      casual: faker.lorem.word(),
+      regular: faker.lorem.word(),
+      formal: faker.lorem.word()
+    };
+    const userScript = faker.lorem.word();
+    const name = faker.lorem.word();
+    const Localizator = {
+      localeData: {
+        [faker.location.countryCode()]: generateLocalizationData({
+          script: faker.lorem.word()
+        }),
+        [locale]: generateLocalizationData({
+          script: userScript,
+          names: {
+            firstNameFirst: true,
+            spacing: true,
+            fallback: expectedResult
+          }
+        })
+      },
+      scripts: {
+        [faker.lorem.word()]: generateScriptData(),
+        [userScript]: generateScriptData()
+      }
+    };
+    const result = guessNamingConvention(
+      Localizator.scripts,
+      Localizator.localeData,
+      name,
+      locale
+    );
+    expect(result).to.equal(expectedResult);
+  });
+
+  it('should use the default if no fallback exist', function () {
+    const locale = faker.location.country();
+    const userScript = faker.lorem.word();
+    const name = faker.lorem.word();
+    const Localizator = {
+      localeData: {
+        [faker.location.countryCode()]: generateLocalizationData(),
+        [locale]: generateLocalizationData({ script: userScript })
+      },
+      scripts: {
+        [faker.lorem.word()]: generateScriptData(),
+        [userScript]: generateScriptData()
+      }
+    };
+    const result = guessNamingConvention(
+      Localizator.scripts,
+      Localizator.localeData,
+      name,
+      locale
+    );
+    expect(result).to.equal(DEFAULT_NAMING_CONVENTION);
+  });
+});

package/src/entities/Localizator/guessNamingConvention/guessNamingConvention.ts

@@ -0,0 +1,58 @@
+import {
+  LocalizatorLocalizationData,
+  LocalizatorScripts,
+  LocalizatorNamingConventions
+} from '../Localizator.types';
+
+export const DEFAULT_NAMING_CONVENTION = {
+  regular: '{firstName} {lastName}',
+  formal: '{firstName}',
+  casual: '{firstName}'
+};
+
+/** Guess the naming convention to use for a given name and locale */
+export function guessNamingConvention(
+  scripts: LocalizatorScripts,
+  localeData: LocalizatorLocalizationData,
+  name: string,
+  locale: string
+): LocalizatorNamingConventions {
+  // When the locale has a specific script
+  // Check if the name matches that script, and use its naming convention
+  if (localeData[locale]?.script) {
+    const defaultScript = localeData[locale].script as string;
+    if (
+      testScriptMatch(scripts, defaultScript, name) &&
+      scripts[defaultScript].names
+    ) {
+      return scripts[defaultScript].names;
+    }
+  }
+
+  // Check if there is a match with any given script and use its naming convention
+  for (const script of Object.keys(scripts)) {
+    if (testScriptMatch(scripts, script, name) && scripts[script].names) {
+      return scripts[script].names;
+    }
+  }
+
+  // Use the current locale's fallback convention
+  if (localeData[locale]?.names?.fallback) {
+    return localeData[locale].names.fallback as LocalizatorNamingConventions;
+  }
+
+  // If everything fails, use the default convention
+  return DEFAULT_NAMING_CONVENTION;
+}
+
+/** Test if a given string is in a given script */
+function testScriptMatch(
+  scripts: LocalizatorScripts,
+  script: string,
+  string: string
+): boolean {
+  if (scripts[script]?.rangeRegex) {
+    return (scripts[script].rangeRegex as RegExp).test(string);
+  }
+  return false;
+}

package/src/entities/Localizator/guessNamingConvention/index.ts

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

package/src/entities/Localizator/index.ts

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

package/src/entities/MessageHandler/MessageHandler.test.ts

@@ -0,0 +1,130 @@
+import Ajv, { JSONSchemaType } from 'ajv';
+import { expect } from 'chai';
+import { faker } from '@faker-js/faker';
+import { fake, match } from 'sinon';
+import { MessageHandler } from './MessageHandler';
+import { SocketClient } from 'entities/SocketClient';
+
+const ajv = new Ajv();
+
+/** */
+interface TestPayload {
+  /** */
+  test?: string;
+}
+
+type TestSchema = JSONSchemaType<TestPayload>;
+
+const schema: TestSchema = {
+  type: 'object',
+  properties: {
+    test: { type: 'string', nullable: true }
+  }
+};
+
+const validator = ajv.compile(schema);
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+const client = { isAuthenticated: () => true } as SocketClient;
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+const unauthenticatedClient = { isAuthenticated: () => false } as SocketClient;
+
+describe('Entities - Message Handler', () => {
+  it('should call the handler', async () => {
+    const type = faker.lorem.word();
+    const handler = fake();
+    const entity = new MessageHandler(type, handler, validator);
+    const message = { type, payload: {} };
+
+    await entity.handle(message, client);
+
+    expect(handler).to.have.been.calledOnceWithExactly(
+      message.payload,
+      match(client)
+    );
+  });
+
+  it('should not call the handler if the type is different', async () => {
+    const handler = fake();
+    const entity = new MessageHandler(faker.lorem.word(), handler, validator);
+    const message = { type: faker.lorem.word(), payload: {} };
+
+    await entity.handle(message, client);
+
+    expect(handler).to.not.have.been.called;
+  });
+
+  it('should not call the handler if the client is not authenticated', async () => {
+    const type = faker.lorem.word();
+    const handler = fake();
+    const entity = new MessageHandler(type, handler, validator);
+    const message = { type, payload: {} };
+
+    await entity.handle(message, unauthenticatedClient);
+
+    expect(handler).to.not.have.been.called;
+  });
+
+  it('should call the handler if the client is not authenticated, but that it is not required', async () => {
+    const type = faker.lorem.word();
+    const handler = fake();
+    const entity = new MessageHandler(type, handler, validator, {
+      authenticated: false
+    });
+    const message = { type, payload: {} };
+
+    await entity.handle(message, unauthenticatedClient);
+
+    expect(handler).to.have.been.calledOnceWithExactly(
+      message.payload,
+      match(unauthenticatedClient)
+    );
+  });
+
+  describe('schema validation', () => {
+    /** */
+    interface TestPayload {
+      /** */
+      test: string;
+    }
+
+    type TestSchema = JSONSchemaType<TestPayload>;
+
+    const schema: TestSchema = {
+      type: 'object',
+      properties: {
+        test: { type: 'string' }
+      },
+      required: ['test']
+    };
+
+    const validator = ajv.compile(schema);
+
+    it('should call the handler if the payload passes validation', async () => {
+      const type = faker.lorem.word();
+      const handler = fake();
+      const entity = new MessageHandler(type, handler, validator);
+      const message = { type, payload: { test: faker.lorem.word() } };
+
+      await entity.handle(message, client);
+
+      expect(handler).to.have.been.calledOnceWithExactly(
+        message.payload,
+        match(client)
+      );
+    });
+
+    it('should throw an error if the payload does not pass validation', async () => {
+      const type = faker.lorem.word();
+      const handler = fake();
+      const entity = new MessageHandler(type, handler, validator);
+      const message = { type, payload: { test: faker.number.int() } };
+
+      const result = entity.handle(message, client);
+      await expect(result).to.be.rejected;
+    });
+  });
+});

package/src/entities/MessageHandler/MessageHandler.ts

@@ -0,0 +1,72 @@
+import { ValidateFunction } from 'ajv';
+import { EngineError } from '../EngineError';
+import {
+  MessageHandlerOptions,
+  MessageHandlerHandler
+} from './MessageHandler.types';
+import { SocketMessage, SocketClient } from 'entities/SocketClient';
+import { WebError } from 'entities/WebError';
+
+/**
+ * Message handlers should be used to define how messages should be handled in web socket servers
+ */
+export class MessageHandler {
+  /** The type of messages that are handled by the instance */
+  public readonly type: string;
+  /** Function that should handle the message */
+  private handler: MessageHandlerHandler;
+  /** Schema against which incoming messages should be validated */
+  private validator: ValidateFunction;
+  /** Indicates that this handler should only run when the client is authenticated */
+  private authenticated: boolean;
+
+  /** Create a new websocket message handler */
+  public constructor(
+    type: string,
+    handler: MessageHandlerHandler,
+    validator: ValidateFunction,
+    options: MessageHandlerOptions = {}
+  ) {
+    if (!type)
+      throw new EngineError({ message: 'MessageHandler has no type defined' });
+    this.type = type;
+    if (!handler)
+      throw new EngineError({
+        message: 'MessageHandler should have a handler function'
+      });
+    this.handler = handler;
+    this.validator = validator;
+    this.authenticated = options.authenticated ?? true;
+  }
+
+  /** Handle received messages, and propagate them to the handler if needed  */
+  public async handle(
+    message: SocketMessage,
+    client: SocketClient
+  ): Promise<void> {
+    const valid = this.validator(message.payload);
+    if (!valid) {
+      const hint = this.validator.errors?.reduce(
+        (hint, error) => ({
+          ...hint,
+          [error.instancePath]: error.message
+            ? `${error.keyword}: ${error.message}`
+            : error.keyword
+        }),
+        {}
+      );
+      throw new WebError({
+        statusCode: 400,
+        errorCode: 'invalid-message',
+        message: 'Message validation failed',
+        data: hint,
+        hint
+      });
+    }
+    // Do not handle if it not for this type of handler
+    if (this.type !== message.type) return;
+    // When handler requires authentication but that client is not authenticated, do not handle the message.
+    if (this.authenticated && !client.isAuthenticated()) return;
+    await this.handler(message.payload ?? {}, client);
+  }
+}

package/src/entities/MessageHandler/MessageHandler.types.ts

@@ -0,0 +1,15 @@
+import { ValidateFunction } from 'ajv';
+import { SocketClient } from 'entities/SocketClient';
+
+/** Initialization options for the message handler */
+export interface MessageHandlerOptions {
+  /** The handler will only be called for authenticated clients (default: true) */
+  authenticated?: boolean;
+  /** Schema to validate the message before passing it to the handler */
+  validator?: ValidateFunction;
+}
+
+export type MessageHandlerHandler = (
+  payload: unknown,
+  client: SocketClient
+) => unknown | Promise<unknown>;

package/src/entities/MessageHandler/index.ts

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