@ikonintegration/ikapi 4.0.1 → 5.0.0

package/src/Server/lib/container/GenericHandlerEvent.ts

@@ -0,0 +1,154 @@
+import type { APIGatewayProxyEvent, Context } from 'aws-lambda'
+import cuid from 'cuid'
+import { Request } from 'express'
+
+import { parseMultiValueQueryStringParameters, parseQueryStringParameters } from './Utils.js'
+import Globals from '../../../Globals.js'
+import Server from '../Server.js'
+
+/**
+ * Represents the response object returned by a generic event handler.
+ * @typedef {Object} GenericHandlerEventResponse
+ * @property {Error | string} [err] - An optional error object or error message.
+ * @property {*} [data] - An optional data object.
+ */
+export type GenericHandlerEventResponse = { err?: Error | string; data?: any }
+
+type HasRawBody = {
+  rawBody: Buffer
+}
+
+/**
+ * Represents a generic handler event for serverless functions.
+ */
+export default class GenericHandlerEvent {
+  /**
+   * Represents an HTTP request.
+   * @property {Request} request - The HTTP request object.
+   */
+  public request: Request
+  /**
+   * The handler function for serverless events in a server.
+   * @param {Server['handleServerlessEvent']} serverlessHandler - The function that handles serverless events.
+   * @returns None
+   */
+  public serverlessHandler: Server['handleServerlessEvent']
+
+  /**
+   * Constructs a new instance of the class.
+   * @param {Request} request - The request object.
+   * @param {Server['handleServerlessEvent']} serverlessHandler - The serverless handler function.
+   * @returns None
+   */
+  constructor(request: Request, serverlessHandler: Server['handleServerlessEvent']) {
+    this.request = request
+    this.serverlessHandler = serverlessHandler
+  }
+
+  /**
+   * Invokes the handler function asynchronously and returns a promise that resolves to a GenericHandlerEventResponse.
+   * @returns {Promise<GenericHandlerEventResponse>} A promise that resolves to a GenericHandlerEventResponse.
+   */
+  public async invoke(): Promise<GenericHandlerEventResponse> {
+    // eslint-disable-next-line no-async-promise-executor
+    return new Promise(async (resolve, reject) => {
+      try {
+        // Build event and context
+        const event = this.buildEvent()
+        const context = this.buildContext(event, (err?: Error | string, data?: any) => {
+          resolve({ err, data })
+        })
+        // Invoke
+        await this.serverlessHandler(event, context)
+      } catch (e) {
+        reject(e) // forward rejection
+      }
+    })
+  }
+
+  /**
+   * Builds and returns an APIGatewayProxyEvent object based on the current request.
+   * @returns {APIGatewayProxyEvent} - The constructed APIGatewayProxyEvent object.
+   */
+  private buildEvent(): APIGatewayProxyEvent & HasRawBody {
+    return {
+      body: this.request.body || null, //enforce key
+      rawBody: this.request['rawBody'],
+      headers: <any>(this.request.headers || {}),
+      httpMethod: this.request.method?.toUpperCase(),
+      isBase64Encoded: false,
+      multiValueHeaders: <any>(this.request.headers || {}),
+      multiValueQueryStringParameters: parseMultiValueQueryStringParameters(this.request.url),
+      path: this.request.path,
+      pathParameters: null,
+      queryStringParameters: this.request.url ? parseQueryStringParameters(this.request.url) : {},
+      requestContext: {
+        accountId: process.env.AWS_ACCOUNT_ID || 'undefined',
+        apiId: '',
+        authorizer: null,
+        domainName: undefined,
+        domainPrefix: undefined,
+        extendedRequestId: cuid(),
+        httpMethod: this.request.method ? this.request.method.toUpperCase() : '',
+        identity: {
+          accessKey: null,
+          accountId: process.env.AWS_ACCOUNT_ID || null,
+          caller: null,
+          apiKey: null,
+          apiKeyId: null,
+          clientCert: null,
+          cognitoAuthenticationProvider: null,
+          cognitoAuthenticationType: null,
+          cognitoIdentityId: null,
+          cognitoIdentityPoolId: null,
+          principalOrgId: null,
+          sourceIp:
+            <string>this.request.headers?.['x-forwarded-for'] ||
+            this.request.socket?.remoteAddress ||
+            '',
+          user: null,
+          userAgent: this.request.headers?.['user-agent'] || null,
+          userArn: null,
+        },
+        path: this.request.path,
+        protocol: 'HTTP/1.1',
+        requestId: `${cuid()}-${cuid()}`,
+        requestTime: new Date().toISOString(),
+        requestTimeEpoch: Date.now(),
+        resourceId: '',
+        resourcePath: Globals.Listener_HTTP_ProxyRoute,
+        stage: process.env.STAGE || '',
+      },
+      resource: Globals.Listener_HTTP_ProxyRoute,
+      stageVariables: null,
+    }
+  }
+
+  /**
+   * Builds and returns a context object for an AWS Lambda function.
+   * @param {APIGatewayProxyEvent} event - The event object passed to the Lambda function.
+   * @param {(err?: Error | string, data?: any) => void} callback - The callback function to be called when the Lambda function completes.
+   * @returns {Context} - The context object for the Lambda function.
+   */
+  private buildContext(
+    event: APIGatewayProxyEvent,
+    callback: (err?: Error | string, data?: any) => void
+  ): Context {
+    return {
+      awsRequestId: event.requestContext.requestId,
+      callbackWaitsForEmptyEventLoop: true,
+      getRemainingTimeInMillis: () => {
+        return 0
+      },
+      done: (err, data) => callback(err, data),
+      fail: err => callback(err),
+      succeed: res => callback(undefined, res),
+      functionName: 'container-function',
+      functionVersion: 'LATEST',
+      invokedFunctionArn: 'none',
+      memoryLimitInMB: '-1',
+      logGroupName: 'undefined',
+      logStreamName: 'undefined',
+    }
+  }
+}

package/src/Server/lib/container/HealthHandler.ts

@@ -0,0 +1,11 @@
+import { Request, Response } from 'express'
+
+/**
+ * Handles a request and sends a response with the message 'Healthy!'.
+ * @param {Request} _request - The request object.
+ * @param {Response} res - The response object.
+ * @returns None
+ */
+export default async (_request: Request, res: Response) => {
+  res.send('Healthy!')
+}

package/src/Server/lib/container/Proxy.ts

@@ -0,0 +1,172 @@
+import fs from 'fs'
+import { Server as HTTPServer, createServer } from 'http'
+
+import cors from 'cors'
+import express from 'express'
+
+import Server from './../Server.js'
+import GenericHandler from './GenericHandler.js'
+import HealthHandler from './HealthHandler.js'
+import Globals from '../../../Globals.js'
+import Utils from '../../../Util/Utils.js'
+import { RouterConfig } from '../../Router.js'
+
+/* Get package.json version from IKApi on ESM */
+const { version: appVersion } = JSON.parse(fs.readFileSync('package.json').toString())
+
+/**
+ * Represents a Proxy class that handles routing and server functionality.
+ */
+export default class Proxy {
+  /**
+   * A boolean flag indicating whether the process is currently stopping or not.
+   */
+  private stopping: boolean
+  /**
+   * The configuration object for the router.
+   */
+  private readonly config: RouterConfig
+  /**
+   * The Express application instance for the server.
+   * @readonly
+   * @type {express.Express}
+   */
+  private readonly app: express.Express
+  /**
+   * The handler function for serverless events in the Server class.
+   * @param {ServerlessEvent} event - The serverless event object.
+   * @returns None
+   */
+  private readonly serverlessHandler: Server['handleServerlessEvent']
+  /**
+   * Represents a listener for an HTTP server.
+   * @private
+   * @type {HTTPServer}
+   */
+  private listener: HTTPServer
+
+  /**
+   * Constructs a new instance of the Router class.
+   * @param {RouterConfig} config - The configuration object for the router.
+   * @param {Server['handleServerlessEvent']} serverlessHandler - The handler function for serverless events.
+   * @returns None
+   */
+  constructor(config: RouterConfig, serverlessHandler: Server['handleServerlessEvent']) {
+    this.stopping = false
+    this.config = config
+    this.serverlessHandler = serverlessHandler
+    this.app = express()
+    /* Opinionated Express configs */
+    this.app.use(
+      express.json({
+        verify(req, res, buf) {
+          req['rawBody'] = buf
+        },
+      })
+    )
+    // apply cors config
+    const corsConfig = this.config.cors || Utils.parseObjectNullIfEmpty(process.env.CORS)
+    this.app.use(
+      cors(
+        corsConfig
+          ? {
+              origin: corsConfig.origin,
+              allowedHeaders: corsConfig.headers,
+              credentials: !!corsConfig.allowCredentials,
+            }
+          : {}
+      )
+    )
+
+    // //This supposedly fix some 502 codes where nodejs socket would hang during
+    // //a request and if behind ALB, it would cause 502 codes. Had experiencied this
+    // //and 502 codes reduced dramastically, but still some appearances. Maybe this
+    // //is just a palliative work-around for the real issue; TODO: need to investigate
+    // //in the future.
+    // this.listener.listener.keepAliveTimeout = 120e3
+    // this.listener.listener.headersTimeout = 120e3
+  }
+
+  /**
+   * Loads the necessary components and initializes the application.
+   * @returns None
+   */
+  public async load() {
+    await this.startListeners()
+    this.installRoutes()
+  }
+
+  /**
+   * Unloads the current module, stopping any active listeners.
+   * @param {any} [err] - Optional error object to pass to the stopListeners method.
+   * @returns {Promise<void>} - A promise that resolves once the listeners have been stopped.
+   */
+  public async unload(err?: any) {
+    await this.stopListeners(err)
+  }
+
+  /**
+   * Starts the listeners for the proxy server.
+   * @returns {Promise<void>} A promise that resolves when the listeners have started.
+   */
+  private async startListeners(): Promise<void> {
+    // eslint-disable-next-line no-async-promise-executor
+    return new Promise(async resolve => {
+      const port = this.config.port || Globals.Listener_HTTP_DefaultPort
+      console.log(`[Proxy] - [STARTING] - v.${appVersion} - :${port}`)
+      // Create Server
+      this.listener = createServer(this.app)
+      // Set defaults
+      this.listener.setTimeout(this.config.timeout || Globals.Listener_HTTP_DefaultTimeout)
+      // Call hook if available
+      if (this.config.containerSetupHook)
+        await this.config.containerSetupHook(this.listener, this.app)
+      // Start Server
+      this.listener.listen(port, () => {
+        console.log(`[Proxy] - [STARTED]`)
+        resolve()
+      })
+    })
+  }
+
+  /**
+   * Stops the listeners and exits the process.
+   * @param {any} [err] - Optional error object.
+   * @returns {Promise<void>} - A promise that resolves when the listeners are stopped and the process is exited.
+   */
+  private async stopListeners(err?: any) {
+    if (this.stopping) return
+    this.stopping = true
+    console.debug('[Proxy] - [STOPPING]')
+    return new Promise(resolve => {
+      this.listener.close(_err => {
+        const err2 = err || _err
+        if (err2) console.log('[Proxy] - exit output:', err2)
+        console.log('[Proxy] - [STOPPED]')
+        process.exit(err2 ? 1 : 0)
+        resolve(null)
+      })
+    })
+  }
+
+  /**
+   * Installs the routes for the proxy server.
+   * @returns None
+   */
+  private installRoutes() {
+    //Health check route -- This is a bypass route to only check if
+    //runtime proxy is working and responding to calls.
+    console.log(
+      `[Proxy] - [HEALTH-ROUTE] - ${
+        this.config.healthCheckRoute || Globals.Listener_HTTP_DefaultHealthCheckRoute
+      }`
+    )
+    this.app
+      .route(this.config.healthCheckRoute || Globals.Listener_HTTP_DefaultHealthCheckRoute)
+      .get(HealthHandler)
+    //Main route -- We use a wildcard route because is not the job of the runtime and neither
+    //the task to deny/constrain routes that invoked this task; all the job is done by the
+    //load balancer and we just foward everything we have to the function.
+    this.app.route(Globals.Listener_HTTP_ProxyRoute).all(GenericHandler(this.serverlessHandler))
+  }
+}

package/src/Server/lib/container/Utils.ts

@@ -0,0 +1,33 @@
+/**
+ * Parses the multi-value query string parameters from the given URL.
+ * @param {string} url - The URL containing the query string parameters.
+ * @returns {Object} - An object representing the parsed query string parameters.
+ */
+export function parseMultiValueQueryStringParameters(url: string) {
+  // dummy placeholder url for the WHATWG URL constructor
+  // https://github.com/nodejs/node/issues/12682
+  const { searchParams } = new URL(url, 'http://example')
+  //
+  if (Array.from(searchParams).length === 0) return {}
+  const map = new Map()
+  // eslint-disable-next-line no-restricted-syntax
+  for (const [key, value] of searchParams) {
+    const item = map.get(key)
+    if (item) item.push(value)
+    else map.set(key, [value])
+  }
+  return Object.fromEntries(map)
+}
+
+/**
+ * Parses the query string parameters from a given URL.
+ * @param {string} url - The URL to parse the query string parameters from.
+ * @returns {object | null} - An object containing the parsed query string parameters, or null if there are no parameters.
+ */
+export function parseQueryStringParameters(url) {
+  // dummy placeholder url for the WHATWG URL constructor
+  // https://github.com/nodejs/node/issues/12682
+  const { searchParams } = new URL(url, 'http://example')
+  if (Array.from(searchParams).length === 0) return {}
+  return Object.fromEntries(searchParams)
+}

package/src/Util/AsyncSingleton.ts

@@ -0,0 +1,86 @@
+type ResolveReject = [(value: void | PromiseLike<void>) => void, (reason?: any) => void]
+
+/**
+ * Represents a class that can be used to create a singleton instance of a class that is created asynchronously.
+ */
+export default class AsyncSingleton<T, R> {
+  private readonly factory: (r: R) => Promise<T>
+  private readonly checker: (value: T) => Promise<boolean>
+
+  private queue: ResolveReject[] = []
+  private instantiating: boolean = false
+
+  private value?: T
+
+  /**
+   * Creates a new instance of the AsyncSingleton class.
+   * @param factory The factory function that creates the instance.
+   * @param checker The function that checks if the instance is valid.
+   */
+  constructor(
+    factory: (r: R) => Promise<T>,
+    checker: (value: T) => Promise<boolean> = async () => true
+  ) {
+    this.factory = factory
+    this.checker = checker
+  }
+
+  /**
+   * Gets the instance of the class.
+   * @param r The configuration object for creating the instance.
+   */
+  public async instance(r: R): Promise<T> {
+    if (this.value && (await this.checker(this.value))) return this.value
+
+    if (this.instantiating) {
+      return await this.awaitOtherInit()
+    }
+
+    return await this.initHere(r)
+  }
+
+  /**
+   * Gets the current value, may be undefined or invalid.
+   */
+  public getValue(): T | undefined {
+    return this.value
+  }
+
+  /**
+   * Clears the current value and rejects all pending promises.
+   */
+  public clear() {
+    this.value = undefined
+    for (const [, rej] of this.queue) {
+      rej()
+    }
+    this.queue = []
+  }
+
+  private async initHere(r: R): Promise<T> {
+    try {
+      this.instantiating = true
+      this.value = await this.factory(r)
+
+      for (const [res] of this.queue) {
+        res()
+      }
+
+      this.queue = []
+
+      return this.value
+    } finally {
+      for (const [, rej] of this.queue) {
+        rej()
+      }
+      this.instantiating = false
+    }
+  }
+
+  private async awaitOtherInit(): Promise<T> {
+    await new Promise<void>((res, rej) => {
+      this.queue.push([res, rej])
+    })
+    return this.value!
+  }
+}

package/src/Util/Utils.ts

@@ -0,0 +1,131 @@
+import child_process from 'child_process'
+
+import { convertToAttr, marshall, unmarshall } from '@aws-sdk/util-dynamodb'
+/**
+ * Utility class containing various static methods for common operations.
+ */
+export default class Utils {
+  /**
+   * Checks if the application is running in a hybridless container.
+   * @returns {boolean} - True if the application is running in a hybridless container, false otherwise.
+   */
+  public static isHybridlessContainer(): boolean {
+    return process.env.HYBRIDLESS_RUNTIME == 'true'
+  }
+
+  /**
+   * Checks if a given string is valid.
+   * @param {string} string - The string to check.
+   * @returns {boolean} - True if the string is valid, false otherwise.
+   */
+  public static isValidString(string: string): boolean {
+    return string?.length > 0 && !Array.isArray(string)
+  }
+
+  /**
+   * Parses a string into an integer and returns null if the string is not a valid number.
+   * @param {string} str - The string to parse into an integer.
+   * @returns {number | null} - The parsed integer or null if the string is not a valid number.
+   */
+  public static parseIntNullIfNaN(str?: string): number | null {
+    const n = parseInt(str || '')
+    return isNaN(n) ? null : n
+  }
+
+  /**
+   * Parses a JSON string and returns the resulting object. If the string is empty or
+   * cannot be parsed, null is returned.
+   * @param {string} string - The JSON string to parse.
+   * @returns {any | null} - The parsed object or null if the string is empty or invalid.
+   */
+  public static parseObjectNullIfEmpty(string: string | undefined): any | null {
+    let o = null
+    try {
+      o = string ? JSON.parse(string) : null
+      if (o && Object.keys(o).length <= 0) o = null
+    } catch (e) {
+      /* empty */
+    }
+    return o
+  }
+
+  /**
+   * Checks if a given value is a valid number.
+   * @param {string} number - The value to be checked.
+   * @returns {boolean} - True if the value is a valid number, false otherwise.
+   */
+  public static isValidNumber(number: string): boolean {
+    let validNumb = NaN
+    try {
+      validNumb = parseInt(number + '')
+    } catch (e) {
+      console.error('Error while validating number', e)
+    }
+    return !isNaN(validNumb) && !Array.isArray(number)
+  }
+
+  /**
+   * Retrieves the value from an object using a case-insensitive key lookup.
+   * @param {any} obj - The object to search for the key.
+   * @param {string} key - The key to search for in the object.
+   * @returns {any | null} The value associated with the key, or null if the key is not found.
+   */
+  public static caseInsensitiveObjectForKey(obj: any, key: string): any | null {
+    if (!obj) return null
+    const insensitiveKey = Object.keys(obj).find(k => k.toLowerCase() === key.toLowerCase())
+    if (insensitiveKey && insensitiveKey != '') return obj[insensitiveKey]
+    return null
+  }
+
+  /**
+   * Cleans out the /tmp directory asynchronously.
+   */
+  public static async cleanTemporaryFolder() {
+    return new Promise<void>(resolve => {
+      try {
+        child_process.execSync('rm -rf /tmp/*')
+        console.log('Cleaned tmp folder')
+      } catch (err) {
+        console.error('Error while cleaning tmp folder', err)
+      } finally {
+        resolve()
+      }
+    })
+  }
+
+  /**
+   * Marshalls the given item into a DynamoDB format.
+   * If the item is an array, it maps over each element and marshalls it recursively.
+   * If the item is an object, it marshalls the object using the marshall function with options to remove undefined values and convert class instances to maps.
+   * If the item is neither an array nor an object, it converts the item to an attribute.
+   * @param {any} item - The item to be marshalled.
+   * @returns The marshalled item in DynamoDB format.
+   */
+  public static ddbMarshall<T>(item: T, rec?: boolean) {
+    if (Array.isArray(item)) return { L: item.map(_i => this.ddbMarshall(_i, true)) }
+    else if (typeof item === 'object' && isNaN(parseInt(item as any))) {
+      const marshalled = marshall(item, {
+        removeUndefinedValues: true,
+        convertClassInstanceToMap: true,
+      })
+      if (rec) return { M: marshalled }
+      else return marshalled
+    } else
+      return convertToAttr(item, { removeUndefinedValues: true, convertClassInstanceToMap: true })
+  }
+
+  /**
+   * Recursively unmarshalls a DynamoDB item by converting it into a plain JavaScript object.
+   * @param {any} item - The DynamoDB item to unmarshall.
+   * @returns {any} The unmarshalled JavaScript object.
+   */
+  public static ddbUnmarshall(item) {
+    if (!item && item !== false) return null
+    if (Array.isArray(item)) {
+      return item.map(_item => this.ddbUnmarshall(_item))
+    } else if (typeof item === 'object') {
+      return unmarshall(item)
+    }
+    return item
+  }
+}

package/src/Validation/Validator.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod'
+
+import Response, { ResponseErrorType } from '../API/Response.js'
+import Globals from '../Globals.js'
+
+/**
+ * Validates the given data against the provided schema.
+ * @param {any} data - The data to be validated.
+ * @param {z.ZodObject<any>} schema - The schema to validate against.
+ * @returns {boolean | Response<ResponseErrorType>} - Returns true if the data is valid, otherwise returns a response object with an error message.
+ */
+export default class Validator {
+  /**
+   * Validates the given data against the provided schema.
+   * @param {any} data - The data to be validated.
+   * @param {z.ZodObject<any> | z.ZodUnion<any>} schema - The schema to validate against.
+   * @returns {boolean | Response<ResponseErrorType>} - Returns either true if the data is valid or a Response object with an error message if validation fails.
+   */
+  public static validateSchema(
+    data: any,
+    schema: z.ZodObject<any> | z.ZodUnion<any> | z.ZodIntersection<any, any>
+  ): boolean | Response<ResponseErrorType> {
+    let error, validatedInput
+
+    // Validate body against known zod schema
+    try {
+      schema.parse(data)
+      validatedInput = true
+    } catch (err: z.ZodError | any) {
+      if (err instanceof z.ZodError) error = JSON.parse(err.message)
+      else error = 'Unknown validation error!' //unhandled case, hard to test
+    }
+
+    // Error validation
+    if (!validatedInput || error) {
+      return Response.BadRequestResponse(
+        Globals.ErrorResponseValidationFail,
+        Globals.ErrorCode_InvalidInput,
+        { validationFailure: error }
+      )
+    } else {
+      return true
+    }
+  }
+}