@jaypie/express 1.1.16 → 1.1.18-rc.0

package/dist/esm/index.js

@@ -0,0 +1,619 @@
+import { CorsError } from '@jaypie/errors';
+import { force, envBoolean, log, JAYPIE, HTTP, validate, getHeaderFrom, jaypieHandler, UnhandledError, GatewayTimeoutError, UnavailableError, BadGatewayError, InternalError, TeapotError, GoneError, MethodNotAllowedError, NotFoundError, ForbiddenError, UnauthorizedError, BadRequestError, NotImplementedError } from '@jaypie/core';
+import expressCors from 'cors';
+import { hasDatadogEnv, submitMetric, DATADOG } from '@jaypie/datadog';
+import { getCurrentInvoke } from '@codegenie/serverless-express';
+
+//
+//
+// Constants
+//
+const EXPRESS = {
+    PATH: {
+        ANY: "*",
+        ID: "/:id",
+        ROOT: /^\/?$/,
+    },
+};
+
+//
+//
+// Constants
+//
+const HTTP_PROTOCOL = "http://";
+const HTTPS_PROTOCOL = "https://";
+const SANDBOX_ENV = "sandbox";
+//
+//
+// Helper Functions
+//
+const ensureProtocol = (url) => {
+    if (!url)
+        return url;
+    if (url.startsWith(HTTP_PROTOCOL) || url.startsWith(HTTPS_PROTOCOL))
+        return url;
+    return HTTPS_PROTOCOL + url;
+};
+const dynamicOriginCallbackHandler = (origin) => {
+    return (requestOrigin, callback) => {
+        // Handle wildcard origin
+        if (origin === "*") {
+            callback(null, true);
+            return;
+        }
+        // Allow requests with no origin (like mobile apps, curl, etc)
+        if (!requestOrigin) {
+            callback(null, true);
+            return;
+        }
+        const allowedOrigins = [];
+        if (process.env.BASE_URL) {
+            allowedOrigins.push(ensureProtocol(process.env.BASE_URL));
+        }
+        if (process.env.PROJECT_BASE_URL) {
+            allowedOrigins.push(ensureProtocol(process.env.PROJECT_BASE_URL));
+        }
+        if (origin) {
+            const additionalOrigins = force.array(origin);
+            allowedOrigins.push(...additionalOrigins);
+        }
+        // Add localhost origins in sandbox
+        if (process.env.PROJECT_ENV === SANDBOX_ENV ||
+            envBoolean("PROJECT_SANDBOX_MODE")) {
+            allowedOrigins.push("http://localhost");
+            allowedOrigins.push(/^http:\/\/localhost:\d+$/);
+        }
+        const isAllowed = allowedOrigins.some((allowed) => {
+            if (allowed instanceof RegExp) {
+                return allowed.test(requestOrigin);
+            }
+            return requestOrigin.includes(allowed);
+        });
+        if (isAllowed) {
+            callback(null, true);
+        }
+        else {
+            callback(new CorsError());
+        }
+    };
+};
+//
+//
+// Main
+//
+const corsHelper = (config = {}) => {
+    const { origin, overrides = {} } = config;
+    const options = {
+        origin: dynamicOriginCallbackHandler(origin),
+        // * The default behavior is to allow any headers and methods so they are not included here
+        ...overrides,
+    };
+    return expressCors(options);
+};
+var cors_helper = (config) => {
+    const cors = corsHelper(config);
+    return (req, res, next) => {
+        cors(req, res, (error) => {
+            if (error) {
+                const corsError = error;
+                res.status(corsError.status);
+                res.setHeader("Content-Type", "application/json");
+                return res.json(corsError.body());
+            }
+            next();
+        });
+    };
+};
+
+//
+//
+// 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;
+    }
+    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.set(HTTP.HEADER.PROJECT.ENVIRONMENT, process.env.PROJECT_ENV);
+        }
+        // X-Project-Handler
+        if (handler) {
+            res.set(HTTP.HEADER.PROJECT.HANDLER, handler);
+        }
+        // X-Project-Invocation
+        const currentInvoke = getCurrentInvokeUuid();
+        if (currentInvoke) {
+            res.set(HTTP.HEADER.PROJECT.INVOCATION, currentInvoke);
+        }
+        // X-Project-Key
+        if (process.env.PROJECT_KEY) {
+            res.set(HTTP.HEADER.PROJECT.KEY, process.env.PROJECT_KEY);
+        }
+        // X-Project-Version
+        if (version) {
+            res.set(HTTP.HEADER.PROJECT.VERSION, version);
+        }
+        //
+        //
+        // Error Handling
+        //
+    }
+    catch (error) {
+        log$1.warn("decorateResponse caught an internal error");
+        log$1.var({ error });
+    }
+};
+//
+//
+// Footnotes
+//
+// 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;
+}
+
+// Cast logger to extended interface for runtime features not in type definitions
+const logger = log;
+function expressHandler(handlerOrOptions, optionsOrHandler) {
+    /* eslint-enable no-redeclare */
+    let handler;
+    let options;
+    // If handler is an object and options is a function, swap them
+    if (typeof handlerOrOptions === "object" &&
+        typeof optionsOrHandler === "function") {
+        handler = optionsOrHandler;
+        options = handlerOrOptions;
+    }
+    else {
+        handler = handlerOrOptions;
+        options = (optionsOrHandler || {});
+    }
+    //
+    //
+    // Validate
+    //
+    let { chaos, locals, name, setup = [], teardown = [], unavailable, validate: validate$1, } = options;
+    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
+        const extReq = req;
+        const extRes = res;
+        // Set default chaos value
+        if (chaos === undefined) {
+            chaos =
+                process.env.PROJECT_CHAOS ||
+                    getHeaderFrom("X-Project-Chaos", req);
+        }
+        // Re-init the logger
+        logger.init();
+        // Very low-level, internal sub-trace details
+        const libLogger = logger.lib({
+            lib: JAYPIE.LIB.EXPRESS,
+        });
+        // Top-level, important details that run at the same level as the main logger
+        const log = logger.lib({
+            level: logger.level,
+            lib: JAYPIE.LIB.EXPRESS,
+        });
+        // Update the public logger with the request ID
+        const invokeUuid = getCurrentInvokeUuid();
+        if (invokeUuid) {
+            logger.tag({ invoke: invokeUuid });
+            logger.tag({ shortInvoke: invokeUuid.slice(0, 8) });
+            // TODO: in theory this is redundant
+            libLogger.tag({ invoke: invokeUuid });
+            libLogger.tag({ shortInvoke: invokeUuid.slice(0, 8) });
+            log.tag({ invoke: invokeUuid });
+            log.tag({ shortInvoke: invokeUuid.slice(0, 8) });
+        }
+        if (!name) {
+            // If handler has a name, use it
+            if (handler.name) {
+                name = handler.name;
+            }
+            else {
+                name = JAYPIE.UNKNOWN;
+            }
+        }
+        logger.tag({ handler: name });
+        // TODO: in theory this is redundant
+        libLogger.tag({ handler: name });
+        log.tag({ handler: name });
+        libLogger.trace("[jaypie] Express init");
+        // Set req.locals if it doesn't exist
+        if (!extReq.locals)
+            extReq.locals = {};
+        if (!extReq.locals._jaypie)
+            extReq.locals._jaypie = {};
+        // Set res.locals if it doesn't exist
+        if (!extRes.locals)
+            extRes.locals = {};
+        if (!extRes.locals._jaypie)
+            extRes.locals._jaypie = {};
+        const originalRes = {
+            attemptedCall: undefined,
+            attemptedParams: undefined,
+            end: res.end.bind(res),
+            json: res.json.bind(res),
+            send: res.send.bind(res),
+            status: res.status.bind(res),
+            statusSent: false,
+        };
+        res.end = ((...endParams) => {
+            originalRes.attemptedCall = originalRes.end;
+            originalRes.attemptedParams = endParams;
+            log.warn("[jaypie] Illegal call to res.end(); prefer Jaypie response conventions");
+            return res;
+        });
+        res.json = ((...jsonParams) => {
+            originalRes.attemptedCall = originalRes.json;
+            originalRes.attemptedParams = jsonParams;
+            log.warn("[jaypie] Illegal call to res.json(); prefer Jaypie response conventions");
+            return res;
+        });
+        res.send = ((...sendParams) => {
+            originalRes.attemptedCall = originalRes.send;
+            originalRes.attemptedParams = sendParams;
+            log.warn("[jaypie] Illegal call to res.send(); prefer Jaypie response conventions");
+            return res;
+        });
+        res.status = ((...statusParams) => {
+            originalRes.statusSent = statusParams[0];
+            return originalRes.status(...statusParams);
+        });
+        //
+        //
+        // Preprocess
+        //
+        if (locals) {
+            // Locals
+            const keys = Object.keys(locals);
+            if (keys.length > 0) {
+                const localsSetup = async (localsReq, localsRes) => {
+                    const extLocalsReq = localsReq;
+                    for (let i = 0; i < keys.length; i += 1) {
+                        const key = keys[i];
+                        libLogger.trace(`[jaypie] Locals: ${key}`);
+                        const localValue = locals[key];
+                        if (typeof localValue === "function") {
+                            extLocalsReq.locals[key] = await localValue(localsReq, localsRes);
+                        }
+                        else {
+                            extLocalsReq.locals[key] = localValue;
+                        }
+                    }
+                };
+                setup.push(localsSetup);
+            }
+        }
+        let response;
+        let status = HTTP.CODE.OK;
+        try {
+            log.info.var({ req: summarizeRequest(req) });
+            // Initialize after logging is set up
+            jaypieFunction = jaypieHandler(handler, {
+                chaos,
+                name,
+                setup,
+                teardown,
+                unavailable,
+                validate: validate$1,
+            });
+            libLogger.trace("[jaypie] Express execution");
+            //
+            //
+            // Process
+            //
+            response = (await jaypieFunction(req, res, ...params));
+            //
+            //
+            // Error Handling
+            //
+        }
+        catch (error) {
+            // In theory jaypieFunction has handled all errors
+            const jaypieError = error;
+            if (jaypieError.status) {
+                status = jaypieError.status;
+            }
+            if (typeof jaypieError.json === "function") {
+                response = jaypieError.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 });
+        // Allow the sent status to override the status in the response
+        if (originalRes.statusSent) {
+            status = originalRes.statusSent;
+        }
+        // Send response
+        try {
+            if (!originalRes.attemptedCall) {
+                // Body
+                if (response) {
+                    if (typeof response === "object") {
+                        if (typeof response.json ===
+                            "function") {
+                            res.json(response.json());
+                        }
+                        else {
+                            res.status(status).json(response);
+                        }
+                    }
+                    else if (typeof response === "string") {
+                        try {
+                            res.status(status).json(JSON.parse(response));
+                        }
+                        catch {
+                            res.status(status).send(response);
+                        }
+                    }
+                    else if (response === true) {
+                        res.status(HTTP.CODE.CREATED).send();
+                    }
+                    else {
+                        res.status(status).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.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),
+        });
+        // Submit metric if Datadog is configured
+        if (hasDatadogEnv()) {
+            // Construct path from baseUrl and url
+            let path = (req.baseUrl || "") + (req.url || "");
+            // Ensure path starts with /
+            if (!path.startsWith("/")) {
+                path = "/" + path;
+            }
+            // Remove trailing slash unless it's the root path
+            if (path.length > 1 && path.endsWith("/")) {
+                path = path.slice(0, -1);
+            }
+            // Replace UUIDs with :id for better aggregation
+            // Matches standard UUID v4 format (8-4-4-4-12 hex characters)
+            path = path.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, ":id");
+            // Determine metric name based on environment variables
+            let metricPrefix = "project";
+            if (process.env.PROJECT_SPONSOR) {
+                metricPrefix = process.env.PROJECT_SPONSOR;
+            }
+            else if (process.env.PROJECT_KEY) {
+                metricPrefix = `project.${process.env.PROJECT_KEY}`;
+            }
+            await submitMetric({
+                name: `${metricPrefix}.api.response`,
+                type: DATADOG.METRIC.TYPE.COUNT,
+                value: 1,
+                tags: {
+                    status: String(res.statusCode),
+                    path,
+                },
+            });
+        }
+        // Clean up the public logger
+        logger.untag("handler");
+        //
+        //
+        // Return
+        //
+        return response;
+    };
+}
+
+//
+//
+// Main
+//
+const httpHandler = (statusCode = HTTP.CODE.OK, context = {}) => {
+    // Give a default name if there isn't one
+    if (!context.name) {
+        context.name = "_http";
+    }
+    // Return a function that will be used as an express route
+    return expressHandler(async (req, res) => {
+        // Map the most throwable status codes to errors and throw them!
+        const error = {
+            [HTTP.CODE.BAD_REQUEST]: BadRequestError,
+            [HTTP.CODE.UNAUTHORIZED]: UnauthorizedError,
+            [HTTP.CODE.FORBIDDEN]: ForbiddenError,
+            [HTTP.CODE.NOT_FOUND]: NotFoundError,
+            [HTTP.CODE.METHOD_NOT_ALLOWED]: MethodNotAllowedError,
+            [HTTP.CODE.GONE]: GoneError,
+            [HTTP.CODE.TEAPOT]: TeapotError,
+            [HTTP.CODE.INTERNAL_ERROR]: InternalError,
+            [HTTP.CODE.BAD_GATEWAY]: BadGatewayError,
+            [HTTP.CODE.UNAVAILABLE]: UnavailableError,
+            [HTTP.CODE.GATEWAY_TIMEOUT]: GatewayTimeoutError,
+        };
+        // If this maps to an error, throw it
+        if (error[statusCode]) {
+            log.trace(`@knowdev/express: gracefully throwing ${statusCode} up to projectHandler`);
+            throw new error[statusCode]();
+        }
+        // If this is an error and we didn't get thrown, log a warning
+        if (statusCode >= 400) {
+            log.warn(`@knowdev/express: status code ${statusCode} not mapped as throwable`);
+        }
+        // Send the response
+        res.status(statusCode);
+        return statusCode === HTTP.CODE.NO_CONTENT ? null : {};
+    }, context);
+};
+
+//
+//
+// Main
+//
+const echoHandler = (context = {}) => {
+    validate.object(context);
+    // Give a default name if there isn't one
+    if (!context.name) {
+        context.name = "_echo";
+    }
+    // Return a function that will be used as an express route
+    return expressHandler(async (req) => {
+        return {
+            req: summarizeRequest(req),
+        };
+    }, context);
+};
+
+//
+//
+// Functions
+//
+const routes = {
+    badRequestRoute: httpHandler(HTTP.CODE.BAD_REQUEST, { name: "_badRequest" }),
+    echoRoute: echoHandler(),
+    forbiddenRoute: httpHandler(HTTP.CODE.FORBIDDEN, { name: "_forbidden" }),
+    goneRoute: httpHandler(HTTP.CODE.GONE, { name: "_gone" }),
+    methodNotAllowedRoute: httpHandler(HTTP.CODE.METHOD_NOT_ALLOWED, {
+        name: "_methodNotAllowed",
+    }),
+    noContentRoute: httpHandler(HTTP.CODE.NO_CONTENT, { name: "_noContent" }),
+    notFoundRoute: httpHandler(HTTP.CODE.NOT_FOUND, { name: "_notFound" }),
+    notImplementedRoute: expressHandler(() => {
+        throw new NotImplementedError();
+    }, { name: "_notImplemented" }),
+};
+//
+//
+// Export
+//
+const badRequestRoute = routes.badRequestRoute;
+const echoRoute = routes.echoRoute;
+const forbiddenRoute = routes.forbiddenRoute;
+const goneRoute = routes.goneRoute;
+const methodNotAllowedRoute = routes.methodNotAllowedRoute;
+const noContentRoute = routes.noContentRoute;
+const notFoundRoute = routes.notFoundRoute;
+const notImplementedRoute = routes.notImplementedRoute;
+
+export { EXPRESS, badRequestRoute, cors_helper as cors, echoRoute, expressHandler, httpHandler as expressHttpCodeHandler, forbiddenRoute, goneRoute, methodNotAllowedRoute, noContentRoute, notFoundRoute, notImplementedRoute };
+//# sourceMappingURL=index.js.map