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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitblit/ratchet-epsilon-common",
-  "version": "6.0.146-alpha",
+  "version": "6.0.147-alpha",
   "description": "Tiny adapter to simplify building API gateway Lambda APIS",
   "sideEffects": false,
   "bin": {
@@ -8,6 +8,7 @@
   },
   "type": "module",
   "files": [
+    "src/**",
     "lib/**",
     "bin/**"
   ],
@@ -66,10 +67,10 @@
     "@aws-sdk/client-sns": "3.922.0",
     "@aws-sdk/client-sqs": "3.922.0",
     "@aws-sdk/types": "3.922.0",
-    "@bitblit/ratchet-aws": "6.0.146-alpha",
-    "@bitblit/ratchet-common": "6.0.146-alpha",
-    "@bitblit/ratchet-misc": "6.0.146-alpha",
-    "@bitblit/ratchet-node-only": "6.0.146-alpha",
+    "@bitblit/ratchet-aws": "6.0.147-alpha",
+    "@bitblit/ratchet-common": "6.0.147-alpha",
+    "@bitblit/ratchet-misc": "6.0.147-alpha",
+    "@bitblit/ratchet-node-only": "6.0.147-alpha",
     "@smithy/abort-controller": "4.2.4",
     "@smithy/smithy-client": "4.9.2",
     "@smithy/util-waiter": "4.2.4",
@@ -86,10 +87,10 @@
   },
   "peerDependencies": {
     "@apollo/server": "^5.1.0",
-    "@bitblit/ratchet-aws": "6.0.146-alpha",
-    "@bitblit/ratchet-common": "6.0.146-alpha",
-    "@bitblit/ratchet-misc": "6.0.146-alpha",
-    "@bitblit/ratchet-node-only": "6.0.146-alpha",
+    "@bitblit/ratchet-aws": "6.0.147-alpha",
+    "@bitblit/ratchet-common": "6.0.147-alpha",
+    "@bitblit/ratchet-misc": "6.0.147-alpha",
+    "@bitblit/ratchet-node-only": "6.0.147-alpha",
     "graphql": "^16.12.0"
   },
   "peerDependenciesMeta": {

package/src/background/background-dynamo-log-table-handler.ts

@@ -0,0 +1,44 @@
+import { BackgroundExecutionListener } from './background-execution-listener.js';
+import { BackgroundExecutionEvent } from './background-execution-event.js';
+import { BackgroundExecutionEventType } from './background-execution-event-type.js';
+import { DynamoRatchetLike } from '@bitblit/ratchet-aws/dynamodb/dynamo-ratchet-like';
+import { BackgroundProcessLogTableEntry } from './background-process-log-table-entry.js';
+import { ContextUtil } from '../util/context-util.js';
+
+/*
+Table should be
+- Hash key : guid
+- Range key: timestamp
+ */
+export class BackgroundDynamoLogTableHandler<T> implements BackgroundExecutionListener<T> {
+  constructor(
+    private dynamo: DynamoRatchetLike,
+    private tableName: string,
+    private env: string,
+    private backgroundQueueName: string,
+  ) {}
+
+  async onEvent(event: BackgroundExecutionEvent<T>): Promise<void> {
+    const entry: BackgroundProcessLogTableEntry = {
+      env: this.env,
+      backgroundQueueName: this.backgroundQueueName,
+      requestId: ContextUtil.currentRequestId(),
+      guid: event.guid,
+      processTypeName: event.processorType,
+      state: event.type.toString(),
+      timestampEpochMs: new Date().getTime(),
+    };
+
+    if (event.type == BackgroundExecutionEventType.DataValidationError) {
+      const errors: string[] = event?.errors?.length ? event.errors : ['No-Error']; // DDB does not allow empty sets
+      entry.errors = errors;
+    } else if (event.type == BackgroundExecutionEventType.ProcessStarting) {
+      entry.params = event.data;
+    } else if (event.type == BackgroundExecutionEventType.ExecutionFailedError) {
+      const errors: string[] = event?.errors?.length ? event.errors : ['No-Error']; // DDB does not allow empty sets
+      entry.errors = errors;
+    }
+
+    await this.dynamo.simplePut(this.tableName, entry);
+  }
+}

package/src/background/background-entry.ts

@@ -0,0 +1,4 @@
+export interface BackgroundEntry<T> {
+  type: string;
+  data: T;
+}

package/src/background/background-execution-event-type.ts

@@ -0,0 +1,9 @@
+// NOTE: This is a psuedo-enum to fix some issues with Typescript enums.  See: https://exploringjs.com/tackling-ts/ch_enum-alternatives.html for details
+export const BackgroundExecutionEventType = {
+  ProcessStarting: 'ProcessStarting',
+  DataValidationError: 'DataValidationError',
+  ExecutionSuccessfullyComplete: 'ExecutionSuccessfullyComplete',
+  ExecutionFailedError: 'ExecutionRuntimeError',
+  NoMatchProcessorName: 'NoMatchProcessorName',
+};
+export type BackgroundExecutionEventType = (typeof BackgroundExecutionEventType)[keyof typeof BackgroundExecutionEventType];

package/src/background/background-execution-event.ts

@@ -0,0 +1,9 @@
+import { BackgroundExecutionEventType } from './background-execution-event-type.js';
+
+export interface BackgroundExecutionEvent<T> {
+  type: BackgroundExecutionEventType;
+  guid: string;
+  processorType: string;
+  data: T;
+  errors?: string[];
+}

package/src/background/background-execution-listener.ts

@@ -0,0 +1,6 @@
+import { BackgroundExecutionEvent } from './background-execution-event.js';
+
+export interface BackgroundExecutionListener<T> {
+  label?: string;
+  onEvent(event: BackgroundExecutionEvent<T>): Promise<void>;
+}

package/src/background/background-handler.ts

@@ -0,0 +1,352 @@
+import { Logger } from '@bitblit/ratchet-common/logger/logger';
+import { ErrorRatchet } from '@bitblit/ratchet-common/lang/error-ratchet';
+import { StringRatchet } from '@bitblit/ratchet-common/lang/string-ratchet';
+import { StopWatch } from '@bitblit/ratchet-common/lang/stop-watch';
+import { Context, ProxyResult, SNSEvent } from 'aws-lambda';
+import { LambdaEventDetector } from '@bitblit/ratchet-aws/lambda/lambda-event-detector';
+import { EpsilonConstants } from '../epsilon-constants.js';
+import { ModelValidator } from '@bitblit/ratchet-misc/model-validator/model-validator';
+import { BackgroundValidator } from './background-validator.js';
+import { BackgroundConfig } from '../config/background/background-config.js';
+import { BackgroundProcessor } from '../config/background/background-processor.js';
+import { InternalBackgroundEntry } from './internal-background-entry.js';
+import { BackgroundTransactionLog } from '../config/background/background-transaction-log.js';
+import { BackgroundExecutionEvent } from './background-execution-event.js';
+import { BackgroundExecutionListener } from './background-execution-listener.js';
+import { BackgroundExecutionEventType } from './background-execution-event-type.js';
+import { EpsilonLambdaEventHandler } from '../config/epsilon-lambda-event-handler.js';
+import { ContextUtil } from '../util/context-util.js';
+import { BackgroundManagerLike } from './manager/background-manager-like.js';
+import { AbstractBackgroundManager } from './manager/abstract-background-manager.js';
+
+/**
+ * We use a FIFO queue so that 2 different Lambdas don't both work on the same
+ * thing at the same time.
+ */
+export class BackgroundHandler implements EpsilonLambdaEventHandler<SNSEvent> {
+  private processors: Map<string, BackgroundProcessor<any>>;
+  private validator: BackgroundValidator;
+
+  constructor(
+    private cfg: BackgroundConfig,
+    private mgr: BackgroundManagerLike,
+    private modelValidator?: ModelValidator,
+  ) {
+    const cfgErrors: string[] = BackgroundValidator.validateConfig(cfg);
+    if (cfgErrors.length > 0) {
+      ErrorRatchet.throwFormattedErr('Invalid background config : %j', cfgErrors);
+    }
+    Logger.silly('Starting Background processor, %d processors', cfg.processors.length);
+    this.validator = new BackgroundValidator(cfg, modelValidator);
+    this.processors = BackgroundValidator.validateAndMapProcessors(cfg.processors, modelValidator);
+
+    // If there is an immediate processing queue, wire me up to use it
+    if (mgr?.immediateProcessQueue && mgr.immediateProcessQueue()) {
+      Logger.info('Attaching to immediate processing queue');
+      mgr.immediateProcessQueue().subscribe(async (evt) => {
+        Logger.debug('Processing local background entry : %j', evt);
+        const rval: boolean = await this.processSingleBackgroundEntry(evt);
+        Logger.info('Processor returned %s', rval);
+      });
+    }
+  }
+
+  public get validProcessorNames(): string[] {
+    return this.processors ? Array.from(this.processors.keys()) : [];
+  }
+
+  public extractLabel(evt: SNSEvent, _context: Context): string {
+    let rval: string = null;
+    if (this.isBackgroundStartSnsEvent(evt)) {
+      rval = 'BG:START-EVT';
+    } else if (this.isBackgroundImmediateFireEvent(evt)) {
+      const pEvt: InternalBackgroundEntry<any> = this.parseImmediateFireBackgroundEntry(evt);
+      rval = 'BG:' + pEvt.type + ':' + pEvt.guid;
+    } else {
+      rval = 'BG:UNKNOWN';
+    }
+    return rval;
+  }
+
+  public handlesEvent(evt: any): boolean {
+    return LambdaEventDetector.isValidSnsEvent(evt) && this.isBackgroundSNSEvent(evt);
+  }
+
+  public isBackgroundSNSEvent(event: any): boolean {
+    return this.isBackgroundStartSnsEvent(event) || this.isBackgroundImmediateFireEvent(event);
+  }
+
+  public isBackgroundStartSnsEvent(event: any): boolean {
+    let rval: boolean = false;
+    if (event) {
+      if (LambdaEventDetector.isSingleSnsEvent(event)) {
+        const cast: SNSEvent = event as SNSEvent;
+        rval = cast.Records[0].Sns.Message === EpsilonConstants.BACKGROUND_SNS_START_MARKER;
+      }
+    }
+    return rval;
+  }
+
+  public isBackgroundImmediateFireEvent(event: any): boolean {
+    let rval: boolean = false;
+
+    if (event) {
+      if (LambdaEventDetector.isSingleSnsEvent(event)) {
+        const cast: SNSEvent = event as SNSEvent;
+        const msg: string = cast.Records[0].Sns.Message;
+        if (StringRatchet.trimToNull(msg)) {
+          const parsed: any = JSON.parse(msg);
+          rval = !!parsed && parsed['type'] === EpsilonConstants.BACKGROUND_SNS_IMMEDIATE_RUN_FLAG;
+        }
+      }
+    }
+    return rval;
+  }
+
+  public parseImmediateFireBackgroundEntry(event: any): InternalBackgroundEntry<any> {
+    let rval: InternalBackgroundEntry<any> = null;
+    try {
+      if (event) {
+        if (LambdaEventDetector.isSingleSnsEvent(event)) {
+          const cast: SNSEvent = event as SNSEvent;
+          const msg: string = cast.Records[0].Sns.Message;
+          if (StringRatchet.trimToNull(msg)) {
+            const parsed: any = JSON.parse(msg);
+            if (!!parsed && parsed['type'] === EpsilonConstants.BACKGROUND_SNS_IMMEDIATE_RUN_FLAG) {
+              rval = parsed['backgroundEntry'];
+            }
+          }
+        }
+      }
+    } catch (err) {
+      Logger.error('Could not parse %j as an immediate run event : %s', event, err, err);
+    }
+    return rval;
+  }
+
+  /*
+  public isBackgroundSqsMessage(message: AWS.SQS.Types.ReceiveMessageResult): boolean {
+    let rval: boolean = false;
+    if (message && message.Messages && message.Messages.length > 0) {
+      const missingFlagField: any = message.Messages.find((se) => {
+        try {
+          const parsed: any = JSON.parse(se.Body);
+          return !parsed[EpsilonConstants.BACKGROUND_SQS_TYPE_FIELD];
+        } catch (err) {
+          Logger.warn('Failed to parse message : %j %s', se, err);
+          return true;
+        }
+      });
+      if (missingFlagField) {
+        Logger.silly('Found at least one message missing a type field');
+      } else {
+        rval = true;
+      }
+    }
+    return rval;
+  }
+
+   */
+
+  // Either trigger a pull of the SQS queue, or process immediately
+
+  public async processEvent(event: any, _context: Context): Promise<ProxyResult> {
+    let procd: number = null;
+    if (!this.isBackgroundStartSnsEvent(event)) {
+      const backgroundEntry: InternalBackgroundEntry<any> = this.parseImmediateFireBackgroundEntry(event);
+      if (backgroundEntry) {
+        Logger.silly('Processing immediate fire event : %j', backgroundEntry);
+        const result: boolean = await this.processSingleBackgroundEntry(backgroundEntry);
+        Logger.silly('Result was : %s', result);
+        procd = 1; // Process a single entry
+      } else {
+        Logger.warn('Tried to process non-background start / immediate event : %j returning false', event);
+      }
+    } else {
+      Logger.info('Reading task from background queue');
+      procd = await this.takeAndProcessSingleBackgroundQueueEntry();
+      if (procd > 0) {
+        Logger.info('Processed %d elements from background queue, refiring', procd);
+        const refire: string = await this.mgr.fireStartProcessingRequest();
+        Logger.info('Refire returned %s', refire);
+      } else {
+        Logger.info('No items processed - stopping');
+      }
+    }
+
+    const rval: ProxyResult = {
+      statusCode: 200,
+      body: StringRatchet.safeString(procd),
+      isBase64Encoded: false,
+    };
+
+    return rval;
+  }
+
+  private async takeAndProcessSingleBackgroundQueueEntry(): Promise<number> {
+    let rval: number = null;
+    const entries: InternalBackgroundEntry<any>[] = await this.mgr.takeEntryFromBackgroundQueue();
+
+    // Do them one at a time since Background is meant to throttle.  Also, it should really
+    // only be one per pull anyway
+    Logger.info('Found %d entries - processing', entries.length);
+    for (const e of entries) {
+      //for (let i = 0; i < entries.length; i++) {
+      //const e: InternalBackgroundEntry<any> = entries[i];
+      const result: boolean = await this.processSingleBackgroundEntry(e);
+      rval += result ? 1 : 0;
+    }
+    Logger.debug('Returning %d', rval);
+
+    return rval;
+  }
+
+  private async safeWriteToLogger(entry: BackgroundTransactionLog): Promise<void> {
+    if (this.cfg.transactionLogger) {
+      try {
+        await this.cfg.transactionLogger.logTransaction(entry);
+      } catch (err) {
+        Logger.error('Failed to write to transaction logger : %j : %s', entry, err, err);
+      }
+    } else {
+      Logger.silly('Skipping - no logger defined');
+    }
+  }
+
+  private async conditionallyStartTransactionLog(e: InternalBackgroundEntry<any>): Promise<void> {
+    if (!StringRatchet.trimToNull(e.guid)) {
+      Logger.warn('No guid found - creating');
+      e.guid = AbstractBackgroundManager.generateBackgroundGuid();
+
+      const log: BackgroundTransactionLog = {
+        request: e,
+        running: true,
+      };
+      await this.safeWriteToLogger(log);
+    }
+    Logger.debug('Starting transaction log');
+  }
+
+  private async conditionallyCompleteTransactionLog(
+    e: InternalBackgroundEntry<any>,
+    result: any,
+    error: any,
+    runtimeMS: number,
+  ): Promise<void> {
+    Logger.debug('Completing transaction log');
+    const log: BackgroundTransactionLog = {
+      request: e,
+      result: result,
+      error: error ? ErrorRatchet.safeStringifyErr(error) : null,
+      running: false,
+      runtimeMS: runtimeMS,
+    };
+    await this.safeWriteToLogger(log);
+  }
+
+  private async conditionallyRunErrorProcessor(e: InternalBackgroundEntry<any>, error: any): Promise<void> {
+    try {
+      if (this.cfg.errorProcessor) {
+        Logger.info('Running error processor');
+        await this.cfg.errorProcessor.handleError(e, error);
+      }
+    } catch (err) {
+      Logger.error('Background : BAD - Failed to run error processor : %s', err, err);
+    }
+  }
+
+  private async fireListenerEvent(event: BackgroundExecutionEvent<any>) {
+    const listeners: BackgroundExecutionListener<any>[] = this.cfg.executionListeners || [];
+    for (const listener of listeners) {
+      try {
+        await listener.onEvent(event);
+      } catch (err) {
+        Logger.error('Failure triggering handler %s : %s', StringRatchet.trimToNull(listener?.label) || 'No-name', err);
+      }
+    }
+  }
+
+  // CAW 2020-08-08 : I am making processSingle public because there are times (such as when
+  // using AWS batch) that you want to be able to run a background command directly, eg, from
+  // the command line without needing an AWS-compliant event wrapping it. Thus, this.
+  public async processSingleBackgroundEntry(inE: InternalBackgroundEntry<any>): Promise<boolean> {
+    let e: InternalBackgroundEntry<any> = inE; // Just to make it clear the input parameter is invariant
+    // Set the trace ids appropriately
+    ContextUtil.setOverrideTraceFromInternalBackgroundEntry(e);
+    Logger.info('Background Process Start: %j', e);
+    const sw: StopWatch = new StopWatch();
+    await this.conditionallyStartTransactionLog(e);
+    if (this?.mgr?.modifyPayloadPreProcess) {
+      Logger.silly('Firing payload pre-process');
+      e = await this.mgr.modifyPayloadPreProcess(e);
+    }
+    let rval: boolean = false;
+    try {
+      await this.fireListenerEvent({
+        type: BackgroundExecutionEventType.ProcessStarting,
+        processorType: e.type,
+        data: e.data,
+        guid: e.guid,
+      });
+
+      const processorInput: BackgroundProcessor<any> = this.processors.get(e.type);
+      if (!processorInput) {
+        ErrorRatchet.throwFormattedErr('Found no processor for background entry : %j (returning false)', e);
+        await this.fireListenerEvent({
+          type: BackgroundExecutionEventType.NoMatchProcessorName,
+          processorType: e.type,
+          data: e.data,
+          guid: e.guid,
+        });
+      }
+
+      let dataValidationErrors: string[] = [];
+      if (StringRatchet.trimToNull(processorInput.dataSchemaName)) {
+        // If it was submitted through HTTP this was checked on the API side, but if they used the
+        // background manager directly (or direct-posted to SQS/SNS) that would have been bypassed.  We'll double
+        // check here
+        dataValidationErrors = this.modelValidator.validate(processorInput.dataSchemaName, e.data, false, false);
+      }
+      if (dataValidationErrors.length > 0) {
+        await this.fireListenerEvent({
+          type: BackgroundExecutionEventType.DataValidationError,
+          processorType: e.type,
+          data: e.data,
+          errors: dataValidationErrors,
+          guid: e.guid,
+        });
+        ErrorRatchet.throwFormattedErr('Not processing, data failed validation; entry was %j : errors : %j', e, dataValidationErrors);
+      } else {
+        let result: any = await processorInput.handleEvent(e.data, this.mgr);
+        result = result || 'SUCCESSFUL COMPLETION : NO RESULT RETURNED';
+        await this.conditionallyCompleteTransactionLog(e, result, null, sw.elapsedMS());
+        await this.fireListenerEvent({
+          type: BackgroundExecutionEventType.ExecutionSuccessfullyComplete,
+          processorType: e.type,
+          data: result,
+          guid: e.guid,
+        });
+        rval = true;
+      }
+    } catch (err) {
+      Logger.error('Background Process Error: %j : %s', e, err, err);
+      await this.conditionallyRunErrorProcessor(e, err);
+      await this.conditionallyCompleteTransactionLog(e, null, err, sw.elapsedMS());
+      await this.fireListenerEvent({
+        type: BackgroundExecutionEventType.ExecutionFailedError,
+        processorType: e.type,
+        data: e.data,
+        errors: [ErrorRatchet.safeStringifyErr(err)],
+        guid: e.guid,
+      });
+    }
+    Logger.info('Background Process Stop: %j : %s', e, sw.dump());
+    return rval;
+  }
+
+  // Returns a copy so you cannot modify the internal one here
+  public getConfig(): BackgroundConfig {
+    const rval: BackgroundConfig = Object.assign({}, this.cfg);
+    return rval;
+  }
+}

package/src/background/background-http-adapter-handler.ts

@@ -0,0 +1,166 @@
+import { Logger } from '@bitblit/ratchet-common/logger/logger';
+import { BackgroundEntry } from './background-entry.js';
+import { Context } from 'aws-lambda';
+import { ExtendedAPIGatewayEvent } from '../config/http/extended-api-gateway-event.js';
+import { BackgroundQueueResponseInternal } from './background-queue-response-internal.js';
+import { BackgroundProcessHandling } from './background-process-handling.js';
+import { BackgroundConfig } from '../config/background/background-config.js';
+import { ModelValidator } from '@bitblit/ratchet-misc/model-validator/model-validator';
+import { BadRequestError } from '../http/error/bad-request-error.js';
+import { BackgroundProcessor } from '../config/background/background-processor.js';
+import { BackgroundMetaResponseInternal } from './background-meta-response-internal.js';
+import { BackgroundTransactionLog } from '../config/background/background-transaction-log.js';
+import { NotFoundError } from '../http/error/not-found-error.js';
+import { BackgroundManagerLike } from './manager/background-manager-like.js';
+import { PromiseRatchet } from '@bitblit/ratchet-common/lang/promise-ratchet';
+import { StringRatchet } from '@bitblit/ratchet-common/lang/string-ratchet';
+import { StopWatch } from '@bitblit/ratchet-common/lang/stop-watch';
+import { BooleanRatchet } from '@bitblit/ratchet-common/lang/boolean-ratchet';
+
+/**
+ * We use a FIFO queue so that 2 different Lambdas don't both work on the same
+ * thing at the same time.
+ */
+export class BackgroundHttpAdapterHandler {
+  constructor(
+    private backgroundConfig: BackgroundConfig,
+    private modelValidator: ModelValidator,
+    private backgroundManager: BackgroundManagerLike,
+    private maxWaitInMsForBackgroundJobToStart: number = 10_000,
+  ) {}
+
+  public get httpMetaEndpoint(): string {
+    return this.backgroundConfig.httpMetaEndpoint;
+  }
+
+  public get httpSubmissionPath(): string {
+    return this.backgroundConfig.httpSubmissionPath;
+  }
+
+  public get httpStatusPath(): string {
+    return this.backgroundConfig.httpStatusEndpoint;
+  }
+
+  public get implyTypeFromPathSuffix(): boolean {
+    return this.backgroundConfig.implyTypeFromPathSuffix;
+  }
+
+  public async handleBackgroundStatusRequest(evt: ExtendedAPIGatewayEvent, _context: Context): Promise<BackgroundTransactionLog> {
+    Logger.info('handleBackgroundStatusRequest called');
+    if (!this.backgroundConfig.transactionLogger) {
+      throw new BadRequestError('Process logging not enabled');
+    } else {
+      const guid: string =
+        StringRatchet.trimToNull(evt.pathParameters['guid']) || StringRatchet.trimToNull(evt.queryStringParameters['guid']);
+      if (guid) {
+        const sw: StopWatch = new StopWatch();
+        let log: BackgroundTransactionLog = null;
+        while (!log && sw.elapsedMS() < this.maxWaitInMsForBackgroundJobToStart) {
+          log = await this.backgroundConfig.transactionLogger.readTransactionLog(guid);
+          if (!log) {
+            Logger.debug(
+              'No log found yet, waiting 500 ms and retrying (%s of %d waited so far)',
+              sw.dump(),
+              this.maxWaitInMsForBackgroundJobToStart,
+            );
+            await PromiseRatchet.wait(500);
+          }
+        }
+
+        if (!log) {
+          throw new NotFoundError().withFormattedErrorMessage('No background result found for guid %s', guid);
+        }
+        return log;
+      } else {
+        throw new BadRequestError('No guid specified');
+      }
+    }
+  }
+
+  public async handleBackgroundMetaRequest(_evt: ExtendedAPIGatewayEvent, _context: Context): Promise<BackgroundMetaResponseInternal> {
+    Logger.info('handleBackgroundMetaRequest called');
+    const currentCount: number = await this.backgroundManager.fetchApproximateNumberOfQueueEntries();
+    const valid: string[] = this.backgroundConfig.processors.map((b) => b.typeName).filter((a) => !!a);
+    valid.sort((a, b) => a.localeCompare(b));
+    const rval: BackgroundMetaResponseInternal = {
+      currentQueueLength: currentCount,
+      validTypes: valid,
+      backgroundManagerName: this.backgroundManager.backgroundManagerName,
+    };
+    return rval;
+  }
+
+  public async handleBackgroundSubmission(evt: ExtendedAPIGatewayEvent, _context: Context): Promise<BackgroundQueueResponseInternal> {
+    Logger.info('handleBackgroundSubmission : %j (mgr:%s)', evt.parsedBody, this.backgroundManager.backgroundManagerName);
+
+    let rval: BackgroundQueueResponseInternal = null;
+
+    const startIdx: number = evt.path.indexOf(this.httpSubmissionPath) + this.httpSubmissionPath.length;
+    let pathSuppliedBackgroundType: string = this.backgroundConfig.implyTypeFromPathSuffix
+      ? evt.path.substring(startIdx).split('-').join('').toLowerCase()
+      : '';
+    // Strip any query params or fragments
+    if (pathSuppliedBackgroundType.includes('?')) {
+      pathSuppliedBackgroundType = pathSuppliedBackgroundType.substring(0, pathSuppliedBackgroundType.indexOf('?'));
+    }
+    if (pathSuppliedBackgroundType.includes('#')) {
+      pathSuppliedBackgroundType = pathSuppliedBackgroundType.substring(0, pathSuppliedBackgroundType.indexOf('#'));
+    }
+
+    const entry: BackgroundEntry<any> = evt.parsedBody || {}; // Many background submissions contain no body (pure triggers)
+
+    // So, either this was configured pathed (like xxx/background/{typename} or non-pathed
+    // like /xxx/background.  If non-pathed, you must supply the type field in the body.  If
+    // pathed, you must either NOT supply the type field in the body, since it'll be determined
+    // by the path, or the types must match
+    if (StringRatchet.trimToNull(pathSuppliedBackgroundType)) {
+      if (StringRatchet.trimToNull(entry?.type) && entry.type.toLocaleLowerCase() !== pathSuppliedBackgroundType.toLocaleLowerCase()) {
+        throw new BadRequestError('Background submission has type but does not match path supplied type');
+      } else {
+        entry.type = pathSuppliedBackgroundType;
+      }
+    } else {
+      // No path, must be in here
+      if (!StringRatchet.trimToNull(entry?.type)) {
+        throw new BadRequestError('Background submission missing type and not configured in pathed mode');
+      }
+    }
+
+    const foundProc: BackgroundProcessor<any> = this.backgroundConfig.processors.find(
+      (s) => s.typeName.toLowerCase() === entry.type.toLowerCase(),
+    );
+    const immediate: boolean = BooleanRatchet.parseBool(evt.queryStringParameters['immediate']);
+    const startProcessor: boolean = BooleanRatchet.parseBool(evt.queryStringParameters['startProcessor']);
+
+    if (foundProc) {
+      // Perform a validation (if this is a path-supplied type it probably already happened, but don't hurt to do it again)
+      // If you're worried about that, and you do path-typing, just don't have your processors set the dataModelName
+      if (StringRatchet.trimToNull(foundProc.dataSchemaName)) {
+        // I'm not allowing empty and extra properties here since this is a fully internally defined object
+        const errors: string[] = this.modelValidator.validate(foundProc.dataSchemaName, entry.data, false, false);
+        if (errors.length > 0) {
+          throw new BadRequestError().withErrors(errors);
+        }
+      }
+
+      let result: string = null;
+      if (immediate) {
+        result = await this.backgroundManager.fireImmediateProcessRequest(entry);
+      } else {
+        result = await this.backgroundManager.addEntryToQueue(entry, startProcessor);
+      }
+
+      rval = {
+        processHandling: immediate ? BackgroundProcessHandling.Immediate : BackgroundProcessHandling.Queued,
+        startProcessorRequested: startProcessor,
+        success: true,
+        resultId: result,
+        error: null,
+      };
+    } else {
+      throw new BadRequestError().withFormattedErrorMessage('Could not find target background processor : %s', entry.type);
+    }
+
+    return rval;
+  }
+}

package/src/background/background-meta-response-internal.ts

@@ -0,0 +1,5 @@
+export interface BackgroundMetaResponseInternal {
+  backgroundManagerName: string;
+  currentQueueLength: number;
+  validTypes: string[];
+}

package/src/background/background-process-handling.ts

@@ -0,0 +1,6 @@
+// NOTE: This is a psuedo-enum to fix some issues with Typescript enums.  See: https://exploringjs.com/tackling-ts/ch_enum-alternatives.html for details
+export const BackgroundProcessHandling = {
+  Queued: 'Queued',
+  Immediate: 'Immediate',
+};
+export type BackgroundProcessHandling = (typeof BackgroundProcessHandling)[keyof typeof BackgroundProcessHandling];

package/src/background/background-process-log-table-entry.ts

@@ -0,0 +1,11 @@
+export interface BackgroundProcessLogTableEntry {
+  env: string;
+  backgroundQueueName: string;
+  requestId: string;
+  guid: string;
+  processTypeName: string;
+  state: string;
+  timestampEpochMs: number;
+  errors?: string[];
+  params?: any;
+}