@bitblit/ratchet-common 6.0.146-alpha → 6.0.147-alpha

package/src/logger/logger.ts

@@ -0,0 +1,213 @@
+import { LogMessage } from './log-message.js';
+import { LogSnapshot } from './log-snapshot.js';
+import { LoggerOptions } from './logger-options.js';
+import { LoggerInstance } from './logger-instance.js';
+import { LogMessageFormatType } from './log-message-format-type.js';
+import { LoggerLevelName } from './logger-level-name.js';
+import { LoggerRingBuffer } from './logger-ring-buffer.js';
+import { LogMessageBuilder } from './log-message-builder.js';
+import { LoggerOutputFunction } from './logger-output-function.js';
+import { GlobalRatchet } from '../lang/global-ratchet.js';
+
+/**
+ * Class to simplify logging across both browsers and node (especially lambda)
+ *
+ * Important note : This class is here to make logging SIMPLE - mainly it is focused on simplicity,
+ * and single point of enable/disable logging. Output goes to console, since thats the only thing
+ * that is present in both the browser and node.  If you need to do something more complicated (like
+ * logging to files,  multiple transports, etc) you really should just use something heavier like
+ * Winston directly and skip this class entirely
+ */
+
+export class Logger {
+  private static LOGGER_INSTANCE_MAP_GLOBAL_KEY = 'RATCHET_GLOBAL_LOGGER_MAP_V01';
+  //private static LOGGER_INSTANCES: Map<string, LoggerInstance> = new Map<string, LoggerInstance>();
+  private static DEFAULT_OPTIONS: LoggerOptions = {
+    initialLevel: LoggerLevelName.info,
+    formatType: LogMessageFormatType.ClassicSingleLine,
+    trace: null,
+    globalVars: {},
+    outputFunction: LoggerOutputFunction.Console,
+    ringBufferSize: 0,
+    preProcessors: [],
+  };
+
+  public static applyDefaultsToOptions(input?: Partial<LoggerOptions>): LoggerOptions {
+    const rval: LoggerOptions = input || {};
+    rval.initialLevel = rval.initialLevel ?? Logger.DEFAULT_OPTIONS.initialLevel;
+    rval.formatType = rval.formatType ?? Logger.DEFAULT_OPTIONS.formatType;
+    rval.trace = rval.trace ?? Logger.DEFAULT_OPTIONS.trace;
+    rval.globalVars = rval.globalVars ?? Logger.DEFAULT_OPTIONS.globalVars;
+    rval.outputFunction = rval.outputFunction ?? Logger.DEFAULT_OPTIONS.outputFunction;
+    rval.ringBufferSize = rval.ringBufferSize ?? Logger.DEFAULT_OPTIONS.ringBufferSize;
+
+    return rval;
+  }
+
+  private static loggerInstances(): Map<string, LoggerInstance> {
+    GlobalRatchet.fetchGlobalVarsRecord(false); // Will throw an exception if global cant setup
+    let rval: Map<string, LoggerInstance> = GlobalRatchet.fetchGlobalVar(Logger.LOGGER_INSTANCE_MAP_GLOBAL_KEY);
+    if (!rval) {
+      rval = new Map<string, LoggerInstance>();
+      GlobalRatchet.setGlobalVar(Logger.LOGGER_INSTANCE_MAP_GLOBAL_KEY, rval);
+    }
+    return rval;
+  }
+
+  public static changeDefaultOptions(input: LoggerOptions, retroactive?: boolean): void {
+    if (!input || !input.initialLevel || !input.formatType) {
+      throw new Error('Default options must be non-null, and provide initial level and format type');
+    }
+    Logger.DEFAULT_OPTIONS = Object.assign({}, input);
+
+    if (retroactive) {
+      Array.from(Logger.loggerInstances().values()).forEach((li) => (li.options = input));
+    }
+  }
+
+  public static getLogger(loggerName = 'default', inOptions?: LoggerOptions): LoggerInstance {
+    let inst: LoggerInstance = Logger.loggerInstances().get(loggerName);
+    if (!inst) {
+      const options: LoggerOptions = Logger.applyDefaultsToOptions(inOptions);
+      inst = new LoggerInstance(loggerName, options);
+      Logger.loggerInstances().set(loggerName, inst);
+    }
+    return inst;
+  }
+
+  // Classic passthru's direct to the default logger
+
+  public static recordMessageBuilder(msgBuild: LogMessageBuilder): string {
+    return Logger.getLogger().recordMessageBuilder(msgBuild);
+  }
+
+  public static levelIsEnabled(level: LoggerLevelName): boolean {
+    return Logger.getLogger().levelIsEnabled(level);
+  }
+
+  public static recordMessage(msg: LogMessage): string {
+    return Logger.getLogger().recordMessage(msg);
+  }
+
+  public static formatMessages(msgs: LogMessage[]): string[] {
+    return Logger.getLogger().formatMessages(msgs);
+  }
+
+  public static updateTracePrefix(newValue: string): void {
+    return Logger.getLogger().updateTracePrefix(newValue);
+  }
+
+  public static changeRingBufferSize(newValue: number): void {
+    return Logger.getLogger().changeRingBufferSize(newValue);
+  }
+
+  public static getRingBuffer(): LoggerRingBuffer {
+    return Logger.getLogger().ringBuffer;
+  }
+
+  public static dumpConfigurationIntoLog(): void {
+    return Logger.getLogger().dumpConfigurationIntoLog();
+  }
+
+  public static dumpOptionsIntoLog(): void {
+    return Logger.getLogger().dumpOptionsIntoLog();
+  }
+
+  public static getLevel(): LoggerLevelName {
+    return Logger.getLogger().level;
+  }
+
+  public static setLevel(newLevel: LoggerLevelName): void {
+    Logger.getLogger().level = newLevel;
+  }
+
+  // Defaulting to silly because it'll typically be post-filtered
+  public static ringBufferOnlyMode(ringBufferSize: number = 1000, initialLevel: LoggerLevelName = LoggerLevelName.silly): void {
+    const newOptions: LoggerOptions = Logger.applyDefaultsToOptions({
+      ringBufferSize: ringBufferSize,
+      outputFunction: LoggerOutputFunction.Disabled,
+      formatType: LogMessageFormatType.SingleLineNoLevel,
+      initialLevel: initialLevel,
+    });
+    Logger.changeDefaultOptions(newOptions, true);
+  }
+
+  public static getOptions(): LoggerOptions {
+    return Logger.getLogger().options;
+  }
+
+  public static getMessages(inStartFrom: number = null, clear = false, reverseSort = false): LogMessage[] {
+    const buf: LoggerRingBuffer = Logger.getLogger().ringBuffer;
+    return buf ? buf.getMessages(inStartFrom, clear, reverseSort) : null;
+  }
+
+  public static consoleLogPassThru(level: LoggerLevelName, ...input: any[]): void {
+    return Logger.getLogger().consoleLogPassThru(level, ...input);
+  }
+
+  public static error(format: string, ...input: any[]): string {
+    return Logger.getLogger().error(format, ...input);
+  }
+
+  public static errorP(...input: any[]): void {
+    return Logger.getLogger().errorP(...input);
+  }
+
+  public static warn(format: string, ...input: any[]): string {
+    return Logger.getLogger().warn(format, ...input);
+  }
+
+  public static warnP(...input: any[]): void {
+    return Logger.getLogger().warnP(...input);
+  }
+
+  public static info(format: string, ...input: any[]): string {
+    return Logger.getLogger().info(format, ...input);
+  }
+
+  public static infoP(...input: any[]): void {
+    return Logger.getLogger().infoP(...input);
+  }
+
+  public static verbose(format: string, ...input: any[]): string {
+    return Logger.getLogger().verbose(format, ...input);
+  }
+
+  public static verboseP(...input: any[]): void {
+    return Logger.getLogger().verboseP(...input);
+  }
+
+  public static debug(format: string, ...input: any[]): string {
+    return Logger.getLogger().debug(format, ...input);
+  }
+
+  public static debugP(...input: any[]): void {
+    return Logger.getLogger().debugP(...input);
+  }
+
+  public static silly(format: string, ...input: any[]): string {
+    return Logger.getLogger().silly(format, ...input);
+  }
+
+  public static sillyP(...input: any[]): void {
+    return Logger.getLogger().sillyP(...input);
+  }
+
+  public static takeSnapshot(): LogSnapshot {
+    const buf: LoggerRingBuffer = Logger.getLogger().ringBuffer;
+    return buf ? buf.takeSnapshot() : null;
+  }
+
+  public static logByLevel(level: LoggerLevelName, format: string, ...input: any[]): void {
+    return Logger.getLogger().logByLevel(level, format, ...input);
+  }
+
+  public static importMessages(msgs: LogMessage[], prefixIn = '', addTimestamp = true): void {
+    return Logger.getLogger().importMessages(msgs, prefixIn, addTimestamp);
+  }
+
+  public static getLastLogMessage(): LogMessage {
+    const buf: LoggerRingBuffer = Logger.getLogger().ringBuffer;
+    return buf ? buf.getLastLogMessage() : null;
+  }
+}

package/src/logger/none-log-message-formatter.ts

@@ -0,0 +1,10 @@
+import { LogMessage } from './log-message.js';
+import { LogMessageFormatter } from './log-message-formatter.js';
+import { LoggerMeta } from './logger-meta.js';
+
+// No-op, useful for testing and turning off all logging
+export class NoneLogMessageFormatter implements LogMessageFormatter {
+  public formatMessage(_msg: LogMessage, _meta: LoggerMeta): string {
+    return null;
+  }
+}

package/src/logger/single-line-no-level-log-message-formatter.ts

@@ -0,0 +1,18 @@
+import { LogMessage } from './log-message.js';
+import { LogMessageFormatter } from './log-message-formatter.js';
+import { LoggerMeta } from './logger-meta.js';
+import { StringRatchet } from '../lang/string-ratchet.js';
+
+// Used when the output will be put into a table with the other fields separate
+export class SingleLineNoLevelLogMessageFormatter implements LogMessageFormatter {
+  public formatMessage(msg: LogMessage, meta: LoggerMeta): string {
+    let tmp: string = null;
+
+    if (msg) {
+      tmp = '';
+      tmp += meta?.options?.trace ? meta.options.trace + ' ' : '';
+      tmp += StringRatchet.format(msg?.messageSource ?? '', ...(msg.subsVars || []));
+    }
+    return tmp;
+  }
+}

package/src/logger/structured-json-log-message-formatter.ts

@@ -0,0 +1,25 @@
+import { LogMessage } from './log-message.js';
+import { LogMessageFormatter } from './log-message-formatter.js';
+import { LoggerMeta } from './logger-meta.js';
+import { StringRatchet } from '../lang/string-ratchet.js';
+
+export class StructuredJsonLogMessageFormatter implements LogMessageFormatter {
+  public formatMessage(msg: LogMessage, meta: LoggerMeta): string {
+    let rval: string = null;
+    if (msg) {
+      const tmp: Record<any, any> = Object.assign({}, meta?.options?.globalVars || {}, msg?.params || {});
+      tmp['msg'] = StringRatchet.format(msg?.messageSource, ...(msg.subsVars || []));
+      tmp['utcDateTime'] = new Date(msg.timestamp).toISOString();
+      tmp['logLevel'] = msg.lvl;
+      if (meta?.options?.trace) {
+        tmp['trace'] = meta.options.trace;
+      }
+      tmp['logName'] = meta.loggerInstanceName;
+      tmp['logId'] = meta.loggerInstanceId;
+
+      rval = JSON.stringify(tmp) + '\n'; // You must have this newline at the end if using stdout instead of console.log
+      // see https://stackoverflow.com/questions/4976466/difference-between-process-stdout-write-and-console-log-in-node-js
+    }
+    return rval;
+  }
+}

package/src/mail/archive-email-result.ts

@@ -0,0 +1,8 @@
+/**
+ * Results of sending an email
+ */
+export interface ArchiveEmailResult<R> {
+  raw: R;
+  error: string;
+  meta: Record<string, any>;
+}

package/src/mail/email-attachment.ts

@@ -0,0 +1,23 @@
+/**
+ * tbd
+ * @interface EmailAttachment
+ */
+export interface EmailAttachment {
+  /**
+   * @type {string}
+   * @memberof EmailAttachment
+   */
+  filename?: string;
+  /**
+   *
+   * @type {string}
+   * @memberof EmailAttachment
+   */
+  contentType?: string;
+  /**
+   *
+   * @type {string}
+   * @memberof EmailAttachment
+   */
+  base64Data?: string;
+}

package/src/mail/mail-sending-provider.ts

@@ -0,0 +1,21 @@
+import { ResolvedReadyToSendEmail } from './resolved-ready-to-send-email.js';
+
+/**
+ * Generic Mail Sender.
+ *
+ * If the provider needs the raw text version, it can call the function in MailerUtil to convert it.
+ * If it provides an archive function, it will be called
+ *
+ * for AWS.
+ *
+ * Params:
+ * ses: AWS SES handler, properly configured
+ * defaultSendingAddress:
+ *
+ * T is the object returned by the Mail sender when you send an email
+ * R is the object returned by the Mail archiver when you archive an email
+ */
+export interface MailSendingProvider<T, R> {
+  sendEmail(mail: ResolvedReadyToSendEmail): Promise<T>;
+  archiveEmail?(mail: ResolvedReadyToSendEmail, rawSendResult: T): Promise<R>;
+}

package/src/mail/mailer-config.ts

@@ -0,0 +1,30 @@
+import { MailSendingProvider } from './mail-sending-provider.js';
+import { RatchetTemplateRenderer } from '../template/ratchet-template-renderer.js';
+
+/**
+ * Configuration options for generic mailer
+ *
+ * T is the object returned by the Mail sender when you send an email
+ * R is the object returned by the Mail archiver when you archive an email
+ */
+export interface MailerConfig<T, R> {
+  // The thing that actually sends the email
+  provider: MailSendingProvider<T, R>;
+  // If no sending email is set, and this is, then it is used
+  defaultSendingAddress?: string;
+  // These addresses get added as BCC to any outbound email
+  // If filters end up removing all destination addresses, this is copied into the destination so they still get sent
+  // This behavior is for dev/demo style configurations where you still want to see the email even though the email
+  // itself isn't sent
+  autoBccAddresses?: string[];
+  // If set, the mailer object can delegate template filling to this template renderer.
+  templateRenderer?: RatchetTemplateRenderer;
+  // If set, any outbound email address will be checked against this list and removed if it does not match
+  // Typically used for testing dev/demo configs
+  allowedDestinationEmails?: RegExp[];
+  // If set, if the txt or html bodies are larger than this they will be auto-converted to attachments
+  // For SES, this should be 10485760 or less as of 2021-01-27
+  maxMessageBodySizeInBytes?: number;
+  // If set, any attachments larger than this are auto-dropped
+  maxAttachmentSizeInBase64Bytes?: number;
+}

package/src/mail/mailer-like.ts

@@ -0,0 +1,38 @@
+import { ReadyToSendEmail } from './ready-to-send-email.js';
+import { ResolvedReadyToSendEmail } from './resolved-ready-to-send-email.js';
+import { SendEmailResult } from './send-email-result.js';
+
+/**
+ * Generic Mail Sender for AWS.
+ *
+ * Params:
+ * ses: AWS SES handler, properly configured
+ * defaultSendingAddress:
+ */
+export interface MailerLike<T, R> {
+  fillEmailBody(
+    rts: ReadyToSendEmail,
+    context: any,
+    htmlTemplateName: string,
+    txtTemplateName?: string,
+    layoutName?: string,
+    partialNames?: string[],
+  ): Promise<ReadyToSendEmail>;
+
+  fillEmailBodyAndSend(
+    rts: ReadyToSendEmail,
+    context: any,
+    htmlTemplateName: string,
+    txtTemplateName?: string,
+    layoutName?: string,
+    partialNames?: string[],
+  ): Promise<SendEmailResult<T, R>>;
+
+  filterEmailsToValid(emails: string[]): string[];
+
+  applyLimitsToBodySizesIfAnyInPlace(rts: ResolvedReadyToSendEmail): void;
+
+  applyLimitsToAttachmentSizesIfAnyInPlace(rts: ResolvedReadyToSendEmail): void;
+
+  sendEmail(inRts: ReadyToSendEmail): Promise<SendEmailResult<T, R>>;
+}

package/src/mail/mailer-util.ts

@@ -0,0 +1,65 @@
+import { ResolvedReadyToSendEmail } from './resolved-ready-to-send-email.js';
+import { RequireRatchet } from '../lang/require-ratchet.js';
+import { StringRatchet } from '../lang/string-ratchet.js';
+
+/**
+ * Helper functions for the mailer, most notably the one that converts it to raw
+ * SMTP
+ */
+export class MailerUtil {
+  public static readonly EMAIL: RegExp = new RegExp('.+@.+\\.[a-z]+');
+
+  // Prevent instantiation
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  private constructor() {}
+
+  public static convertResolvedReadyToSendEmailToRaw(rts: ResolvedReadyToSendEmail): string {
+    RequireRatchet.notNullOrUndefined(rts, 'RTS must be defined');
+    RequireRatchet.notNullOrUndefined(rts.destinationAddresses, 'Destination addresses must be defined');
+
+    const toLine: string = 'To: ' + rts.destinationAddresses.join(', ') + '\n';
+    const bccLine: string = !!rts.bccAddresses && rts.bccAddresses.length > 0 ? 'Bcc: ' + rts.bccAddresses.join(', ') + '\n' : '';
+
+    const from: string = rts.fromAddress;
+    const boundary = 'NextPart';
+    const altBoundary = 'AltPart';
+    let rawMail: string = 'From: ' + from + '\n';
+    rawMail += toLine;
+    rawMail += bccLine;
+    rawMail += 'Subject: ' + rts.subject + '\n';
+    rawMail += 'MIME-Version: 1.0\n';
+    rawMail += 'Content-Type: multipart/mixed; boundary="' + boundary + '"\n';
+
+    rawMail += '\n\n--' + boundary + '\n';
+    rawMail += 'Content-Type: multipart/alternative; boundary="' + altBoundary + '"\n';
+    if (StringRatchet.trimToNull(rts.htmlMessage)) {
+      rawMail += '\n\n--' + altBoundary + '\n';
+      rawMail += 'Content-Type: text/html; charset="UTF-8"\n\n';
+      rawMail += rts.htmlMessage;
+    }
+    if (StringRatchet.trimToNull(rts.txtMessage)) {
+      rawMail += '\n\n--' + altBoundary + '\n';
+      rawMail += 'Content-Type: text/plain\n\n';
+      rawMail += rts.txtMessage;
+    }
+
+    rawMail += '\n\n--' + altBoundary + '--\n';
+
+    if (rts.attachments) {
+      rts.attachments.forEach((a) => {
+        rawMail += '\n\n--' + boundary + '\n';
+        rawMail += 'Content-Type: ' + a.contentType + '; name="' + a.filename + '"\n';
+        rawMail += 'Content-Transfer-Encoding: base64\n';
+        rawMail += 'Content-Disposition: attachment\n\n';
+        rawMail += a.base64Data.replace(/([^\0]{76})/g, '$1\n') + '\n\n';
+      });
+    }
+    rawMail += '\n\n--' + boundary + '--\n';
+
+    return rawMail;
+  }
+
+  public static validEmail(email: string): boolean {
+    return email !== null && MailerUtil.EMAIL.test(email);
+  }
+}

package/src/mail/mailer.spec.ts

@@ -0,0 +1,120 @@
+import { ReadyToSendEmail } from './ready-to-send-email.js';
+import { Mailer } from './mailer.js';
+import { EmailAttachment } from './email-attachment.js';
+import { MailerConfig } from './mailer-config.js';
+import { StringRatchet } from '../lang/string-ratchet.js';
+import { Base64Ratchet } from '../lang/base64-ratchet.js';
+import { TestMailSendingProvider } from './test-mail-sending-provider.js';
+import { SendEmailResult } from './send-email-result.js';
+import { describe, expect, test } from 'vitest';
+
+const smallImageBase64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII';
+
+describe('#mailer', function () {
+  const testProvider: TestMailSendingProvider = new TestMailSendingProvider();
+  //beforeEach(() => {});
+
+  test('should send email', async () => {
+    const config: MailerConfig<string, string> = {
+      provider: testProvider,
+      defaultSendingAddress: 'test1@test.com',
+      autoBccAddresses: [], //['test2@test.com','test2@test.com'],
+    };
+    const svc: Mailer<string, string> = new Mailer<string, string>(config);
+
+    const attach1: EmailAttachment = {
+      filename: 'test.txt',
+      contentType: 'text/plain',
+      base64Data: Base64Ratchet.generateBase64VersionOfString('This is a test2'),
+    };
+
+    const attach2: EmailAttachment = {
+      filename: 'a2.png',
+      contentType: 'image/png',
+      base64Data: smallImageBase64,
+    };
+
+    const rts: ReadyToSendEmail = {
+      txtMessage: 'test txt',
+      htmlMessage: '<h1>Test html</h1><p>Test paragraph</p>',
+      subject: 'Test subject',
+      fromAddress: 'test@test.com',
+      destinationAddresses: ['testout@test.com'],
+      attachments: [attach1, attach2],
+    };
+
+    const result: SendEmailResult<string, string> = await svc.sendEmail(rts);
+
+    expect(result).toBeTruthy();
+  });
+
+  test('should allow for unicode in email subject', async () => {
+    const config: MailerConfig<string, string> = {
+      provider: testProvider,
+      defaultSendingAddress: 'jflint@adomni.com',
+      autoBccAddresses: [],
+    };
+    const svc: Mailer<string, string> = new Mailer<string, string>(config);
+    const rts: ReadyToSendEmail = {
+      txtMessage: 'test txt',
+      htmlMessage: '<h1>Test html</h1><p>Test paragraph</p>',
+      subject: "Rappel: Votre panneau d'affichage Shout est diffusé aujourd'hui!", // <==== We are testing these unicode characters
+      fromAddress: 'jflint@adomni.com',
+      destinationAddresses: ['jflint@adomni.com'],
+    };
+
+    const result: SendEmailResult<string, string> = await svc.sendEmail(rts);
+    expect(result).toBeTruthy();
+  });
+
+  test('should filter outbound', async () => {
+    const config: MailerConfig<string, string> = {
+      provider: testProvider,
+      allowedDestinationEmails: [/.*test\.com/, /.*.test2\.com/],
+    };
+    const svc: Mailer<string, string> = new Mailer<string, string>(config);
+
+    const out1: string[] = ['a@test.com', 'b@fail.com'];
+    const res1: string[] = svc.filterEmailsToValid(out1);
+    expect(res1).toBeTruthy();
+    expect(res1.length).toEqual(1);
+
+    const out2: string[] = ['a@fail.com', 'b@fail.com'];
+    const res2: string[] = svc.filterEmailsToValid(out2);
+    expect(res2).toBeTruthy();
+    expect(res2.length).toEqual(0);
+  });
+
+  test('should fix a huge text/html body', async () => {
+    const config: MailerConfig<string, string> = {
+      provider: testProvider,
+      defaultSendingAddress: 'test@test.com',
+      autoBccAddresses: [], //['test2@test.com','test2@test.com'],
+      maxMessageBodySizeInBytes: 500,
+      maxAttachmentSizeInBase64Bytes: 1000,
+    };
+    const svc: Mailer<string, string> = new Mailer<string, string>(config);
+
+    const bigBody: string = StringRatchet.createRandomHexString(300);
+
+    const bigAttach: EmailAttachment = {
+      filename: 'test.txt',
+      contentType: 'text/plain',
+      base64Data: Base64Ratchet.generateBase64VersionOfString(StringRatchet.createRandomHexString(2000)),
+    };
+
+    const rts: ReadyToSendEmail = {
+      txtMessage: bigBody,
+      htmlMessage: bigBody,
+      subject: 'Test big message',
+      fromAddress: 'test@test.com',
+      destinationAddresses: ['test@test.com'],
+      attachments: [bigAttach],
+    };
+
+    const result: SendEmailResult<string, string> = await svc.sendEmail(rts);
+
+    expect(result).toBeTruthy();
+  });
+});