@ikonintegration/ikapi 4.0.1 → 5.0.0

package/src/Server/RouteResolver.ts

@@ -0,0 +1,124 @@
+import { AnyRoute, RouterConfig } from './Router.js'
+import { HttpMethod } from '../API/Request.js'
+
+/**
+ * Represents a collection of routes that can be added and resolved.
+ */
+class Routes {
+  /**
+   * Represents the current route.
+   * @type {Route | undefined}
+   */
+  private current?: AnyRoute
+  /**
+   * Optional private variable that represents a collection of routes.
+   * @type {Routes | undefined}
+   */
+  private variable?: Routes
+  /**
+   * An object that maps string keys to Routes.
+   * @private
+   * @readonly
+   * @type {Object.<string, Routes>}
+   */
+  private readonly next: { [k: string]: Routes }
+  /**
+   * Initializes a new instance of the class.
+   * @constructor
+   */
+  constructor() {
+    this.next = {}
+  }
+
+  /**
+   * Adds a route to the routing system.
+   * @param {Route} route - The route to add.
+   * @param {string[]} parts - The parts of the route path.
+   * @returns None
+   * @throws {Error} If a duplicate route is detected.
+   */
+  public addRoute(route: AnyRoute, parts: string[]): void {
+    const first = parts.shift()
+    if (first) {
+      if (first.startsWith(':')) {
+        this.variable = this.variable || new Routes()
+        this.variable.addRoute(route, parts)
+      } else {
+        this.next[first] = this.next[first] || new Routes()
+        this.next[first].addRoute(route, parts)
+      }
+    } else {
+      if (this.current) throw new Error(`Duplicate route: ${route.method}: ${route.path}`)
+
+      this.current = route
+    }
+  }
+
+  /**
+   * Resolves a route based on the given parts.
+   * @param {string[]} parts - An array of route parts.
+   * @returns {Route} The resolved route.
+   */
+  public resolveRoute(parts: string[]): AnyRoute | undefined {
+    const first = parts.shift()
+    if (first) {
+      if (first in this.next) {
+        return this.next[first].resolveRoute(parts)
+      }
+      return this.variable?.resolveRoute(parts)
+    }
+    return this.current
+  }
+}
+
+/**
+ * A class that resolves routes based on the provided configuration.
+ * @class RouteResolver
+ */
+export default class RouteResolver {
+  /**
+   * An object that maps HTTP methods to their corresponding routes.
+   * @property {object} routes - The routes object.
+   * @property {Routes} routes.method - The routes for the specified HTTP method.
+   */
+  private routes: { [method in HttpMethod]?: Routes }
+
+  /**
+   * Constructs a new instance of the Router class with the given configuration.
+   * @param {RouterConfig} config - The configuration object for the router.
+   * @returns None
+   */
+  constructor(config: RouterConfig) {
+    this.routes = {}
+    this.buildRoutes(config)
+  }
+
+  /**
+   * Resolves a route based on the given HTTP method and path.
+   * @param {string} method - The HTTP method of the request.
+   * @param {string} path - The path of the request.
+   * @returns {Route | undefined} - The resolved route or undefined if no route is found.
+   */
+  public resolveRoute(method: HttpMethod, path: string): AnyRoute | undefined {
+    const parts = path.split('/').filter(p => p.length)
+    return this.routes[method]?.resolveRoute(parts)
+  }
+
+  /**
+   * Builds the routes for the router based on the given configuration.
+   * @param {RouterConfig} config - The router configuration object.
+   * @returns None
+   */
+  private buildRoutes(config: RouterConfig): void {
+    const addRoute = (path: string, route: AnyRoute) => {
+      const parts = path.split('/').filter(p => p.length)
+      this.routes[route.method] = this.routes[route.method] || new Routes()
+      this.routes[route.method]!.addRoute(route, parts)
+    }
+    for (const route of config.routes) {
+      if (Array.isArray(route.path)) {
+        for (const path of route.path) addRoute(path, route)
+      } else addRoute(route.path, route)
+    }
+  }
+}

package/src/Server/Router.ts

@@ -0,0 +1,200 @@
+import { Server as HTTPServer } from 'http'
+
+import express from 'express'
+import { z } from 'zod'
+
+import ContainerServer from './lib/ContainerServer.js'
+import Server from './lib/Server.js'
+import { HttpMethod } from '../API/Request.js'
+import { ResponseErrorType } from '../API/Response.js'
+import Transaction, {
+  TransactionConfig,
+  TransactionExecution,
+  StringMap,
+} from '../BaseEvent/Transaction.js'
+import Utils from '../Util/Utils.js'
+
+/**
+ * Represents a route in an API.
+ * @template InputType - The type of the input data for the route.
+ * @template OutputType - The type of the output data for the route.
+ * @property {string} path - The path of the route.
+ * @property {string} method - The HTTP method of the route.
+ * @property {TransactionExecution<Transaction<InputType, OutputType | ResponseErrorType>, OutputType | ResponseErrorType>} handler - The handler function for the route.
+ * @property {?z.ZodObject<any> | z.ZodUnion<any> | z.ZodIntersection<any, any>}[inputSchema] - The input schema for validating the input data.
+ * @property {?z.ZodObject<any> | z.ZodUnion<any> | z.ZodIntersection<any, any>}[pathSchema] - The path schema for validating the path data.
+ * @property {?z.ZodObject<any> | z.ZodUnion<any> | z.ZodIntersection<any, any>}[querySchema] - The query schema for validating the query data.
+ */
+export interface Route<
+  InputType = never,
+  OutputType = never,
+  PathParamsType = StringMap,
+  QueryParamsType = StringMap,
+> {
+  /**
+   * Represents a file path as a string.
+   * @param {string} path - The file path.
+   * @returns None
+   */
+  path: string | string[]
+  /**
+   * Represents the method used in an API request.
+   * @type {string}
+   */
+  method: HttpMethod
+  /* If you are here to know why implementing this method
+    does not auto infer the param type, check long discussion on TS 
+    - https://github.com/Microsoft/TypeScript/issues/1373
+    - https://github.com/microsoft/TypeScript/issues/23911#issuecomment-1351020050 (proposed solution)
+    - https://github.com/microsoft/TypeScript/issues/10570
+  */
+  /**
+   * Represents a handler for executing a transaction with the given input type and output type.
+   * @param {Transaction<InputType, OutputType | ResponseErrorType, PathParamsType, QueryParamsType>} transaction - The transaction to execute.
+   * @param {OutputType | ResponseErrorType} - The output type or response error type of the transaction.
+   */
+  handler: TransactionExecution<
+    Transaction<InputType, OutputType | ResponseErrorType, never, PathParamsType, QueryParamsType>,
+    OutputType | ResponseErrorType
+  >
+  /**
+   * An optional input schema for validating the structure of the input data.
+   *
+   * @type {?z.ZodObject<any> | z.ZodUnion<any> | z.ZodIntersection<any, any>}
+   */
+  inputSchema?: z.ZodObject<any> | z.ZodUnion<any> | z.ZodIntersection<any, any>
+
+  /**
+   * An optional input schema for validating the structure of the path params.
+   *
+   * @type {?z.ZodObject<any> | z.ZodUnion<any> | z.ZodIntersection<any, any>}
+   */
+  pathSchema?: z.ZodObject<any> | z.ZodUnion<any> | z.ZodIntersection<any, any>
+
+  /**
+   * An optional input schema for validating the structure of the query params.
+   *
+   * @type {?z.ZodObject<any> | z.ZodUnion<any> | z.ZodIntersection<any, any>}
+   */
+  querySchema?: z.ZodObject<any> | z.ZodUnion<any> | z.ZodIntersection<any, any>
+
+  /**
+   * An optional openApi object with extra metadata for docs generation.
+   */
+  openApi?: {
+    // Descriptive
+    summary: string
+    description: string
+    tags?: string[]
+    // Response
+    outputSchema?: z.ZodObject<any> | z.ZodUnion<any> | z.ZodIntersection<any, any> | z.ZodType<any>
+    successCode?: number /* defaults to 200 */
+    // Sec
+    security?: {
+      [key: string]: string[] | never[]
+    }[]
+  }
+}
+
+/**
+ * Represents a route that can accept any type for its parameters and return values.
+ */
+export type AnyRoute = Route<any | never, any | never, any | never, any | never>
+
+/**
+ * Represents the configuration options for a router.
+ * @typedef {TransactionConfig & {
+ *   routes: Route[]
+ *   port?: number
+ *   timeout?: number
+ *   cors?: {
+ *     origin?: string | string[]
+ *     headers?: string[]
+ *     allowCredentials?: boolean
+ *   }
+ *   healthCheckRoute?: string
+ * }} RouterConfig
+ * @property {Route[]} routes - The routes to be configured in the router.
+ * @property {number} [port] - The port number to listen on. If not specified, a default port will be used.
+ * @property {number} [timeout] - The timeout duration for requests in milliseconds. If not specified, a default timeout will be
+ */
+export type RouterConfig = TransactionConfig & {
+  /**
+   * An array of route objects representing the available routes in the application.
+   * @type {Route[]}
+   */
+  routes: AnyRoute[]
+  /**
+   * The port number for the server to listen on.
+   * @type {number | undefined}
+   */
+  port?: number
+  /**
+   * Optional timeout value in milliseconds.
+   * @type {number | undefined}
+   */
+  timeout?: number
+  /**
+   * Configuration options for Cross-Origin Resource Sharing (CORS).
+   * @property {string | string[]} [origin] - The allowed origin(s) for CORS requests.
+   * @property {string[]} [headers] - The allowed headers for CORS requests.
+   * @property {boolean} [allowCredentials] - Whether to allow credentials (cookies, HTTP authentication, and client-side SSL certificates) to be sent in CORS requests.
+   */
+  cors?: {
+    origin?: string | string[]
+    headers?: string[]
+    allowCredentials?: boolean
+  }
+  /**
+   * The route for the health check endpoint.
+   * @type {string | undefined}
+   */
+  healthCheckRoute?: string
+  /**
+   * Optional hook function that sets up the container with the provided HTTP server and Express app.
+   * @param {HTTPServer} server - The HTTP server instance.
+   * @param {express.Express} app - The Express application instance.
+   * @returns {Promise<void>} A promise that resolves when the setup is complete.
+   */
+  containerSetupHook?: (server: HTTPServer, app: express.Express) => Promise<void>
+}
+
+/**
+ * Represents a router that handles routing logic for a web application.
+ */
+export default class Router {
+  /**
+   * The configuration object for the router.
+   */
+  private readonly config: RouterConfig
+  /**
+   * The private readonly server instance.
+   */
+  private readonly server: Server
+
+  /**
+   * Constructs a new instance of the Router class.
+   * @param {RouterConfig} config - The configuration object for the router.
+   * @returns None
+   */
+  constructor(config: RouterConfig) {
+    this.config = config
+    this.server = this.isContainer() ? new ContainerServer(config) : new Server(config)
+  }
+
+  /**
+   * Retrieves the export function from the server.
+   * @returns {CallableFunction} The export function from the server.
+   */
+  public getExport(): CallableFunction {
+    return this.server.getExport()
+  }
+
+  /**
+   * Checks if the current element is a container.
+   * @returns {boolean} - True if the element is a container, false otherwise.
+   */
+  private isContainer(): boolean {
+    return Utils.isHybridlessContainer()
+  }
+}

package/src/Server/lib/ContainerServer.ts

@@ -0,0 +1,65 @@
+import Proxy from './container/Proxy.js'
+import Server from './Server.js'
+import { RouterConfig } from '../Router.js'
+
+/**
+ * Represents a server container that extends the Server class and handles serverless events.
+ */
+export default class ContainerServer extends Server {
+  /**
+   * The proxy object used for handling requests and responses.
+   * @type {Proxy}
+   * @protected
+   */
+  protected readonly proxy: Proxy
+
+  /**
+   * Constructs a new instance of the Router class.
+   * @param {RouterConfig} config - The configuration object for the router.
+   * @returns None
+   */
+  constructor(config: RouterConfig) {
+    super(config)
+    this.proxy = new Proxy(config, this.handleServerlessEvent.bind(this))
+    this.listenProcessEvents()
+  }
+
+  /**
+   * Returns a callable function that can be used to export data.
+   * @returns {CallableFunction} - A callable function that can be used to export data.
+   */
+  public getExport(): CallableFunction {
+    // start server socket
+    this.start()
+    // return empty function, we are all done
+    return () => {}
+  }
+
+  /**
+   * Starts the application by loading the proxy.
+   * @returns {Promise<void>} - A promise that resolves when the proxy is loaded.
+   */
+  public async start() {
+    await this.proxy.load()
+  }
+
+  /**
+   * Stops the execution of the program and unloads the proxy.
+   * @param {any} [err] - Optional error object to pass to the unload method.
+   * @returns {Promise<void>} - A promise that resolves once the proxy is unloaded.
+   */
+  public async stop(err?: any) {
+    await this.proxy.unload(err)
+  }
+
+  /**
+   * Listens for process events and handles them accordingly.
+   * @private
+   * @returns None
+   */
+  private listenProcessEvents() {
+    // start process listeners
+    process.on('unhandledRejection', this.stop.bind(this)) // listen to exceptions
+    process.on('SIGINT', this.stop.bind(this)) // listen on SIGINT signal and gracefully stop the server
+  }
+}

package/src/Server/lib/Server.ts

@@ -0,0 +1,109 @@
+import { APIGatewayProxyEvent, Context } from 'aws-lambda'
+import { pathToRegexp } from 'path-to-regexp'
+
+import Request from '../../API/Request.js'
+import Response, { ResponseErrorType } from '../../API/Response.js'
+import Transaction, { StringMap } from '../../BaseEvent/Transaction.js'
+import Validator from '../../Validation/Validator.js'
+import { RouterConfig } from '../Router.js'
+import RouteResolver from '../RouteResolver.js'
+
+/**
+ * Represents a server that handles serverless events and routes them to appropriate handlers.
+ */
+export default class Server {
+  /**
+   * The configuration object for the router.
+   * @readonly
+   * @type {RouterConfig}
+   */
+  protected readonly config: RouterConfig
+  /**
+   * A protected property that holds a RouteResolver object.
+   * The RouteResolver is responsible for resolving routes and returning the appropriate response.
+   * @type {RouteResolver}
+   */
+  protected readonly routeResolver: RouteResolver
+
+  /**
+   * Constructs a new instance of the Router class.
+   * @param {RouterConfig} config - The configuration object for the router.
+   * @returns None
+   */
+  constructor(config: RouterConfig) {
+    this.config = config
+    this.routeResolver = new RouteResolver(config)
+  }
+
+  /**
+   * Returns a callable function that is bound to the `handleServerlessEvent` method of the current object.
+   * @returns {CallableFunction} - A callable function that is bound to the `handleServerlessEvent` method.
+   */
+  public getExport(): CallableFunction {
+    return this.handleServerlessEvent.bind(this)
+  }
+
+  /**
+   * Handles a serverless event by executing a transaction and resolving the route based on the event.
+   * @param {APIGatewayProxyEvent} event - The serverless event object.
+   * @param {Context} context - The serverless context object.
+   * @returns None
+   */
+  public async handleServerlessEvent(event: APIGatewayProxyEvent, context: Context) {
+    // init transaction
+    await new Transaction<never, ResponseErrorType, never, StringMap, StringMap>(
+      event,
+      context,
+      this.config
+    ).execute(async transaction => {
+      const request = transaction.request
+      const route = this.routeResolver.resolveRoute(request.getMethod(), request.getPath())
+      if (route) {
+        transaction.logger.log('Router accepted route:', route.path)
+        // Validate input
+        if (route.inputSchema) {
+          const validationResp = Validator.validateSchema(request.getBody(), route.inputSchema)
+          if (validationResp && validationResp instanceof Response) return validationResp
+        }
+
+        // Validate query
+        if (route.querySchema) {
+          const validationResp = Validator.validateSchema(
+            request.getQueryParams(),
+            route.querySchema
+          )
+          if (validationResp && validationResp instanceof Response) return validationResp
+        }
+
+        // parse before validating
+        for (const path of Array.isArray(route.path) ? route.path : [route.path]) {
+          this.parsePathParams(request, path)
+        }
+
+        // Validate path
+        if (route.pathSchema) {
+          const validationResp = Validator.validateSchema(request.getPathParams(), route.pathSchema)
+          if (validationResp && validationResp instanceof Response) return validationResp
+        }
+
+        // Continue to route handler
+        return await route.handler(transaction)
+      }
+      //No route found :/
+      return new Response(404, { err: 'Route not found!' })
+    })
+  }
+
+  /**
+   * Parses the path parameters from the request URL based on the given route path.
+   * @param {Request<any>} req - The request object.
+   * @param {string} routePath - The route path pattern to match against.
+   * @returns None
+   */
+  private parsePathParams(req: Request<any, any, any>, routePath: string) {
+    const path = req.getPath()
+    const regex = pathToRegexp(routePath)
+    const result = regex.regexp.exec(path)
+    if (result) req.setFixedPathParams(regex.keys, result)
+  }
+}

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

@@ -0,0 +1,76 @@
+import { Request, Response } from 'express'
+
+import GenericHandlerEvent, { GenericHandlerEventResponse } from './GenericHandlerEvent.js'
+import Globals from '../../../Globals.js'
+import Utils from '../../../Util/Utils.js'
+import Server from '../Server.js'
+
+/**
+ * Creates an async function that handles serverless events and sends a response.
+ * @param {Server['handleServerlessEvent']} serverlessHandler - The serverless handler function.
+ * @returns {Function} - An async function that handles the request and sends a response.
+ */
+export default (serverlessHandler: Server['handleServerlessEvent']) => {
+  /**
+   * Handles an HTTP request by invoking a serverless function and processing the response.
+   * @param {Request} request - The HTTP request object.
+   * @param {Response} res - The HTTP response object.
+   * @returns None
+   */
+  return async (request: Request, res: Response) => {
+    const startTime = Date.now()
+    try {
+      // Generate event with request stuff (http to serverless translation)
+      const event = new GenericHandlerEvent(request, serverlessHandler)
+      // Invoke
+      const invokationResp = await event.invoke()
+      // Respond
+      processServerlessResponse(invokationResp, res)
+    } catch (e) {
+      console.error('[Proxy] - Exception during execution!', e)
+      console.error(e.stack)
+      res.status(Globals.Resp_STATUSCODE_EXCEPTION).json({
+        ...e,
+        err: Globals.Resp_MSG_EXCEPTION,
+        errCode: Globals.Resp_CODE_EXCEPTION,
+      })
+    }
+    console.debug(`[Proxy] - Request took ${Date.now() - startTime}ms`)
+  }
+}
+
+/**
+ * Processes the response received from a serverless function invocation and sends the appropriate response back to the client.
+ * @param {GenericHandlerEventResponse} invokation - The response object received from the serverless function invocation.
+ * @param {Response} res - The response object to send back to the client.
+ * @returns The response object to send back to the client.
+ */
+const processServerlessResponse = (invokation: GenericHandlerEventResponse, res: Response) => {
+  // translate answer to http layer
+  if (invokation && invokation.err) {
+    // err came
+    return res.json({ err: invokation.err }).status(400)
+  } else if (!invokation || !invokation.data) {
+    // invalid response came
+    return res.status(Globals.Resp_STATUSCODE_INVALIDRESP).json({
+      err: Globals.Resp_MSG_INVALIDRESP,
+      errCode: Globals.Resp_CODE_INVALIDRESP,
+    })
+  } else {
+    // Check for headers
+    if (invokation.data.headers) {
+      for (const hKey of Object.keys(invokation.data.headers)) {
+        res.header(hKey, invokation.data.headers[hKey])
+      }
+    }
+    //
+    let response = res.status(invokation.data.statusCode)
+    // check for stream
+    if (invokation.data?.body?.pipe) {
+      invokation.data.body.pipe(response)
+    } else {
+      response = response.json(Utils.parseObjectNullIfEmpty(invokation.data.body) || {})
+    }
+    return response
+  }
+}