@jaypie/express 0.1.0 → 0.1.2

package/dist/module.cjs.js

@@ -1,10 +1,390 @@
 'use strict';
 
+var core = require('@jaypie/core');
+var serverlessExpress = require('@codegenie/serverless-express');
+
+//
+//
+// Helper Functions
+//
+
+// Adapter for the "@codegenie/serverless-express" uuid
+function getServerlessExpressUuid() {
+  const currentInvoke = serverlessExpress.getCurrentInvoke();
+  if (
+    currentInvoke &&
+    currentInvoke.context &&
+    currentInvoke.context.awsRequestId
+  ) {
+    return currentInvoke.context.awsRequestId;
+  }
+  return undefined;
+}
+
+//
+//
+// Main
+//
+
+const getCurrentInvokeUuid = () => getServerlessExpressUuid();
+
+//
+//
+// Main
+//
+
+const decorateResponse = (
+  res,
+  { handler = "", version = process.env.PROJECT_VERSION } = {},
+) => {
+  const log = core.log.lib({
+    lib: core.JAYPIE.LIB.EXPRESS,
+  });
+
+  //
+  //
+  // Validate
+  //
+  if (typeof res !== "object" || res === null) {
+    log.warn("decorateResponse called but response is not an object");
+    return; // eslint-disable-line no-useless-return
+  }
+
+  try {
+    //
+    //
+    // Decorate Headers
+    //
+
+    // X-Powered-By, override "Express" but nothing else
+    if (
+      !res.get(core.HTTP.HEADER.POWERED_BY) ||
+      res.get(core.HTTP.HEADER.POWERED_BY) === "Express"
+    ) {
+      res.set(core.HTTP.HEADER.POWERED_BY, core.JAYPIE.LIB.EXPRESS);
+    }
+
+    // X-Project-Environment
+    if (process.env.PROJECT_ENV) {
+      res.setHeader(core.HTTP.HEADER.PROJECT.ENVIRONMENT, process.env.PROJECT_ENV);
+    }
+
+    // X-Project-Handler
+    if (handler) {
+      res.setHeader(core.HTTP.HEADER.PROJECT.HANDLER, handler);
+    }
+
+    // X-Project-Invocation
+    const currentInvoke = getCurrentInvokeUuid();
+    if (currentInvoke) {
+      res.setHeader(core.HTTP.HEADER.PROJECT.INVOCATION, currentInvoke);
+    }
+
+    // X-Project-Key
+    if (process.env.PROJECT_KEY) {
+      res.setHeader(core.HTTP.HEADER.PROJECT.KEY, process.env.PROJECT_KEY);
+    }
+
+    // X-Project-Version
+    if (version) {
+      res.setHeader(core.HTTP.HEADER.PROJECT.VERSION, version);
+    }
+
+    //
+    //
+    // Error Handling
+    //
+  } catch (error) {
+    log.warn("decorateResponse caught an internal error");
+    log.var({ error });
+  }
+};
+
+//
 //
+// Footnotes
 //
-// Export
+
+// This is a "utility" function but it needs a lot of "context"
+// about the environment's secret parameters, the special adapter,
+// HTTP, etc.  There must be a better way to organize this
+
+//
+//
+// Function Definition
+//
+
+function summarizeRequest(req) {
+  // If body is a buffer, convert it to a string
+  let { body } = req;
+  if (Buffer.isBuffer(body)) {
+    body = body.toString();
+  }
+
+  return {
+    baseUrl: req.baseUrl,
+    body,
+    headers: req.headers,
+    method: req.method,
+    query: req.query,
+    url: req.url,
+  };
+}
+
 //
+//
+// Function Definition
+//
+
+function summarizeResponse(res, extras) {
+  const response = {
+    statusCode: res.statusCode,
+    statusMessage: res.statusMessage,
+  };
+  if (typeof res.getHeaders === "function") {
+    response.headers = res.getHeaders();
+  }
+  if (typeof extras === "object" && extras !== null) {
+    Object.assign(response, extras);
+  }
+  return response;
+}
+
+//
+//
+// Main
+//
+
+const expressHandler = (
+  handler,
+  { locals, name, setup = [], teardown = [], unavailable, validate } = {},
+) => {
+  //
+  //
+  // Validate
+  //
+  core.validate.function(handler);
+  core.validate.optional.object(locals);
+  setup = core.force.array(setup); // allows a single item
+  teardown = core.force.array(teardown); // allows a single item
+
+  //
+  //
+  // Setup
+  //
+
+  let jaypieFunction;
+
+  return async (req, res, ...params) => {
+    // * This is the first line of code that runs when a request is received
+
+    // Update the public logger with the request ID
+    core.log.tag({ invoke: getCurrentInvokeUuid() });
+
+    // Very low-level, internal sub-trace details
+    const libLogger = core.log.lib({
+      lib: core.JAYPIE.LIB.EXPRESS,
+    });
+    libLogger.trace("[jaypie] Express init");
+
+    // Top-level, important details that run at the same level as the main logger
+    const log = core.log.lib({
+      level: core.log.level,
+      lib: core.JAYPIE.LIB.EXPRESS,
+    });
+
+    // Set req.locals if it doesn't exist
+    if (!req.locals) req.locals = {};
+    if (!req.locals._jaypie) req.locals._jaypie = {};
+
+    // Set res.locals if it doesn't exist
+    if (!res.locals) res.locals = {};
+    if (!res.locals._jaypie) res.locals._jaypie = {};
+
+    const originalRes = {
+      attemptedCall: undefined,
+      attemptedParams: undefined,
+      end: res.end,
+      json: res.json,
+      send: res.send,
+      status: res.status,
+      statusSent: false,
+    };
+    res.end = (...params) => {
+      originalRes.attemptedCall = originalRes.end;
+      originalRes.attemptedParams = params;
+      log.warn(
+        "[jaypie] Illegal call to res.end(); prefer Jaypie response conventions",
+      );
+    };
+    res.json = (...params) => {
+      originalRes.attemptedCall = originalRes.json;
+      originalRes.attemptedParams = params;
+      log.warn(
+        "[jaypie] Illegal call to res.json(); prefer Jaypie response conventions",
+      );
+    };
+    res.send = (...params) => {
+      originalRes.attemptedCall = originalRes.send;
+      originalRes.attemptedParams = params;
+      log.warn(
+        "[jaypie] Illegal call to res.send(); prefer Jaypie response conventions",
+      );
+    };
+    res.status = (...params) => {
+      originalRes.statusSent = true;
+      return originalRes.status(...params);
+    };
+
+    //
+    //
+    // Preprocess
+    //
+
+    if (locals) {
+      // Locals
+      const keys = Object.keys(locals);
+      if (keys.length > 0) {
+        const localsSetup = async () => {
+          libLogger.trace("[jaypie] Locals");
+          for (let i = 0; i < keys.length; i += 1) {
+            const key = keys[i];
+            if (typeof locals[key] === "function") {
+              // eslint-disable-next-line no-await-in-loop
+              req.locals[key] = await locals[key](req, res);
+            } else {
+              req.locals[key] = locals[key];
+            }
+          }
+        };
+        setup.push(localsSetup);
+      }
+    }
+
+    if (!jaypieFunction) {
+      // Initialize after logging is set up
+      jaypieFunction = core.jaypieHandler(handler, {
+        name,
+        setup,
+        teardown,
+        unavailable,
+        validate,
+      });
+    }
+
+    let response;
+    let status;
+
+    try {
+      libLogger.trace("[jaypie] Lambda execution");
+      log.info.var({ req: summarizeRequest(req) });
+
+      //
+      //
+      // Process
+      //
+
+      response = await jaypieFunction(req, res, ...params);
+
+      //
+      //
+      // Error Handling
+      //
+    } catch (error) {
+      // In theory jaypieFunction has handled all errors
+      if (error.status) {
+        status = error.status;
+      }
+      if (typeof error.json === "function") {
+        response = error.json();
+      } else {
+        // This should never happen
+        const unhandledError = new core.UnhandledError();
+        response = unhandledError.json();
+        status = unhandledError.status;
+      }
+    }
+
+    //
+    //
+    // Postprocess
+    //
+
+    // Restore original res functions
+    res.end = originalRes.end;
+    res.json = originalRes.json;
+    res.send = originalRes.send;
+    res.status = originalRes.status;
+
+    // Decorate response
+    decorateResponse(res, { handler: name });
+
+    // Send response
+    try {
+      // Status
+      if (status && !originalRes.statusSent) {
+        res.status(status);
+      }
+
+      if (!originalRes.attemptedCall) {
+        // Body
+        if (response) {
+          if (typeof response === "object") {
+            if (typeof response.json === "function") {
+              res.json(response.json());
+            } else {
+              res.json(response);
+            }
+          } else if (typeof response === "string") {
+            try {
+              res.json(JSON.parse(response));
+            } catch (error) {
+              res.send(response);
+            }
+          } else if (response === true) {
+            res.status(core.HTTP.CODE.CREATED);
+            res.send();
+          } else {
+            res.send(response);
+          }
+        } else {
+          // No response
+          res.status(core.HTTP.CODE.NO_CONTENT).send();
+        }
+      } else {
+        // Resolve illegal call to res.end(), res.json(), or res.send()
+        log.debug("[jaypie] Resolving illegal call to res");
+        log.var({
+          attemptedCall: {
+            name: originalRes.attemptedCall.name,
+            params: originalRes.attemptedParams,
+          },
+        });
+        // Call the original function with the original parameters and the original `this` (res)
+        originalRes.attemptedCall.call(res, ...originalRes.attemptedParams);
+      }
+    } catch (error) {
+      log.fatal("Express encountered an error while sending the response");
+      log.var({ responseError: error });
+    }
+
+    // Log response
+    const extras = {};
+    if (response) extras.body = response;
+    log.info.var({
+      res: summarizeResponse(res, extras),
+    });
+
+    // Clean up the public logger
+    core.log.untag("handler");
+
+    //
+    //
+    // Return
+    //
 
-var index = {};
+    return response;
+  };
+};
 
-module.exports = index;
+exports.expressHandler = expressHandler;

package/dist/module.esm.js

@@ -1,8 +1,388 @@
+import { log, JAYPIE, HTTP, validate, force, jaypieHandler, UnhandledError } from '@jaypie/core';
+import { getCurrentInvoke } from '@codegenie/serverless-express';
+
+//
+//
+// Helper Functions
+//
+
+// Adapter for the "@codegenie/serverless-express" uuid
+function getServerlessExpressUuid() {
+  const currentInvoke = getCurrentInvoke();
+  if (
+    currentInvoke &&
+    currentInvoke.context &&
+    currentInvoke.context.awsRequestId
+  ) {
+    return currentInvoke.context.awsRequestId;
+  }
+  return undefined;
+}
+
+//
+//
+// Main
+//
+
+const getCurrentInvokeUuid = () => getServerlessExpressUuid();
+
+//
+//
+// Main
+//
+
+const decorateResponse = (
+  res,
+  { handler = "", version = process.env.PROJECT_VERSION } = {},
+) => {
+  const log$1 = log.lib({
+    lib: JAYPIE.LIB.EXPRESS,
+  });
+
+  //
+  //
+  // Validate
+  //
+  if (typeof res !== "object" || res === null) {
+    log$1.warn("decorateResponse called but response is not an object");
+    return; // eslint-disable-line no-useless-return
+  }
+
+  try {
+    //
+    //
+    // Decorate Headers
+    //
+
+    // X-Powered-By, override "Express" but nothing else
+    if (
+      !res.get(HTTP.HEADER.POWERED_BY) ||
+      res.get(HTTP.HEADER.POWERED_BY) === "Express"
+    ) {
+      res.set(HTTP.HEADER.POWERED_BY, JAYPIE.LIB.EXPRESS);
+    }
+
+    // X-Project-Environment
+    if (process.env.PROJECT_ENV) {
+      res.setHeader(HTTP.HEADER.PROJECT.ENVIRONMENT, process.env.PROJECT_ENV);
+    }
+
+    // X-Project-Handler
+    if (handler) {
+      res.setHeader(HTTP.HEADER.PROJECT.HANDLER, handler);
+    }
+
+    // X-Project-Invocation
+    const currentInvoke = getCurrentInvokeUuid();
+    if (currentInvoke) {
+      res.setHeader(HTTP.HEADER.PROJECT.INVOCATION, currentInvoke);
+    }
+
+    // X-Project-Key
+    if (process.env.PROJECT_KEY) {
+      res.setHeader(HTTP.HEADER.PROJECT.KEY, process.env.PROJECT_KEY);
+    }
+
+    // X-Project-Version
+    if (version) {
+      res.setHeader(HTTP.HEADER.PROJECT.VERSION, version);
+    }
+
+    //
+    //
+    // Error Handling
+    //
+  } catch (error) {
+    log$1.warn("decorateResponse caught an internal error");
+    log$1.var({ error });
+  }
+};
+
+//
 //
+// Footnotes
 //
-// Export
+
+// This is a "utility" function but it needs a lot of "context"
+// about the environment's secret parameters, the special adapter,
+// HTTP, etc.  There must be a better way to organize this
+
+//
+//
+// Function Definition
+//
+
+function summarizeRequest(req) {
+  // If body is a buffer, convert it to a string
+  let { body } = req;
+  if (Buffer.isBuffer(body)) {
+    body = body.toString();
+  }
+
+  return {
+    baseUrl: req.baseUrl,
+    body,
+    headers: req.headers,
+    method: req.method,
+    query: req.query,
+    url: req.url,
+  };
+}
+
 //
+//
+// Function Definition
+//
+
+function summarizeResponse(res, extras) {
+  const response = {
+    statusCode: res.statusCode,
+    statusMessage: res.statusMessage,
+  };
+  if (typeof res.getHeaders === "function") {
+    response.headers = res.getHeaders();
+  }
+  if (typeof extras === "object" && extras !== null) {
+    Object.assign(response, extras);
+  }
+  return response;
+}
+
+//
+//
+// Main
+//
+
+const expressHandler = (
+  handler,
+  { locals, name, setup = [], teardown = [], unavailable, validate: validate$1 } = {},
+) => {
+  //
+  //
+  // Validate
+  //
+  validate.function(handler);
+  validate.optional.object(locals);
+  setup = force.array(setup); // allows a single item
+  teardown = force.array(teardown); // allows a single item
+
+  //
+  //
+  // Setup
+  //
+
+  let jaypieFunction;
+
+  return async (req, res, ...params) => {
+    // * This is the first line of code that runs when a request is received
+
+    // Update the public logger with the request ID
+    log.tag({ invoke: getCurrentInvokeUuid() });
+
+    // Very low-level, internal sub-trace details
+    const libLogger = log.lib({
+      lib: JAYPIE.LIB.EXPRESS,
+    });
+    libLogger.trace("[jaypie] Express init");
+
+    // Top-level, important details that run at the same level as the main logger
+    const log$1 = log.lib({
+      level: log.level,
+      lib: JAYPIE.LIB.EXPRESS,
+    });
+
+    // Set req.locals if it doesn't exist
+    if (!req.locals) req.locals = {};
+    if (!req.locals._jaypie) req.locals._jaypie = {};
+
+    // Set res.locals if it doesn't exist
+    if (!res.locals) res.locals = {};
+    if (!res.locals._jaypie) res.locals._jaypie = {};
+
+    const originalRes = {
+      attemptedCall: undefined,
+      attemptedParams: undefined,
+      end: res.end,
+      json: res.json,
+      send: res.send,
+      status: res.status,
+      statusSent: false,
+    };
+    res.end = (...params) => {
+      originalRes.attemptedCall = originalRes.end;
+      originalRes.attemptedParams = params;
+      log$1.warn(
+        "[jaypie] Illegal call to res.end(); prefer Jaypie response conventions",
+      );
+    };
+    res.json = (...params) => {
+      originalRes.attemptedCall = originalRes.json;
+      originalRes.attemptedParams = params;
+      log$1.warn(
+        "[jaypie] Illegal call to res.json(); prefer Jaypie response conventions",
+      );
+    };
+    res.send = (...params) => {
+      originalRes.attemptedCall = originalRes.send;
+      originalRes.attemptedParams = params;
+      log$1.warn(
+        "[jaypie] Illegal call to res.send(); prefer Jaypie response conventions",
+      );
+    };
+    res.status = (...params) => {
+      originalRes.statusSent = true;
+      return originalRes.status(...params);
+    };
+
+    //
+    //
+    // Preprocess
+    //
+
+    if (locals) {
+      // Locals
+      const keys = Object.keys(locals);
+      if (keys.length > 0) {
+        const localsSetup = async () => {
+          libLogger.trace("[jaypie] Locals");
+          for (let i = 0; i < keys.length; i += 1) {
+            const key = keys[i];
+            if (typeof locals[key] === "function") {
+              // eslint-disable-next-line no-await-in-loop
+              req.locals[key] = await locals[key](req, res);
+            } else {
+              req.locals[key] = locals[key];
+            }
+          }
+        };
+        setup.push(localsSetup);
+      }
+    }
+
+    if (!jaypieFunction) {
+      // Initialize after logging is set up
+      jaypieFunction = jaypieHandler(handler, {
+        name,
+        setup,
+        teardown,
+        unavailable,
+        validate: validate$1,
+      });
+    }
+
+    let response;
+    let status;
+
+    try {
+      libLogger.trace("[jaypie] Lambda execution");
+      log$1.info.var({ req: summarizeRequest(req) });
+
+      //
+      //
+      // Process
+      //
+
+      response = await jaypieFunction(req, res, ...params);
+
+      //
+      //
+      // Error Handling
+      //
+    } catch (error) {
+      // In theory jaypieFunction has handled all errors
+      if (error.status) {
+        status = error.status;
+      }
+      if (typeof error.json === "function") {
+        response = error.json();
+      } else {
+        // This should never happen
+        const unhandledError = new UnhandledError();
+        response = unhandledError.json();
+        status = unhandledError.status;
+      }
+    }
+
+    //
+    //
+    // Postprocess
+    //
+
+    // Restore original res functions
+    res.end = originalRes.end;
+    res.json = originalRes.json;
+    res.send = originalRes.send;
+    res.status = originalRes.status;
+
+    // Decorate response
+    decorateResponse(res, { handler: name });
+
+    // Send response
+    try {
+      // Status
+      if (status && !originalRes.statusSent) {
+        res.status(status);
+      }
+
+      if (!originalRes.attemptedCall) {
+        // Body
+        if (response) {
+          if (typeof response === "object") {
+            if (typeof response.json === "function") {
+              res.json(response.json());
+            } else {
+              res.json(response);
+            }
+          } else if (typeof response === "string") {
+            try {
+              res.json(JSON.parse(response));
+            } catch (error) {
+              res.send(response);
+            }
+          } else if (response === true) {
+            res.status(HTTP.CODE.CREATED);
+            res.send();
+          } else {
+            res.send(response);
+          }
+        } else {
+          // No response
+          res.status(HTTP.CODE.NO_CONTENT).send();
+        }
+      } else {
+        // Resolve illegal call to res.end(), res.json(), or res.send()
+        log$1.debug("[jaypie] Resolving illegal call to res");
+        log$1.var({
+          attemptedCall: {
+            name: originalRes.attemptedCall.name,
+            params: originalRes.attemptedParams,
+          },
+        });
+        // Call the original function with the original parameters and the original `this` (res)
+        originalRes.attemptedCall.call(res, ...originalRes.attemptedParams);
+      }
+    } catch (error) {
+      log$1.fatal("Express encountered an error while sending the response");
+      log$1.var({ responseError: error });
+    }
+
+    // Log response
+    const extras = {};
+    if (response) extras.body = response;
+    log$1.info.var({
+      res: summarizeResponse(res, extras),
+    });
+
+    // Clean up the public logger
+    log.untag("handler");
+
+    //
+    //
+    // Return
+    //
 
-var index = {};
+    return response;
+  };
+};
 
-export { index as default };
+export { expressHandler };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/express",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "author": "Finlayson Studio",
   "type": "module",
   "exports": {

package/src/index.js

@@ -1,6 +1 @@
-//
-//
-// Export
-//
-
-export default {};
+export { default as expressHandler } from "./expressHandler.js";