@salesforce/mrt-utilities 0.0.1 → 0.1.1

package/dist/cjs/middleware/middleware.js

@@ -0,0 +1,416 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * @fileoverview MRT (Managed Runtime) Middleware for Express.js applications.
+ *
+ * This module provides middleware functions for handling requests in a managed runtime environment,
+ * including request processing, proxy configuration, static asset serving, and local development
+ * utilities. It's designed to work with Salesforce Commerce Cloud's managed runtime platform.
+ *
+ * @author Salesforce Commerce Cloud
+ * @version 0.0.1
+ */
+import { Headers } from '../utils/ssr-proxying.js';
+import { configureProxying, } from '../utils/configure-proxying.js';
+import express from 'express';
+import fs from 'fs';
+import path from 'path';
+import mimeTypes from 'mime-types';
+import qs from 'qs';
+const MOBIFY_PATH = '/mobify';
+const PROXY_PATH_BASE = `${MOBIFY_PATH}/proxy`;
+const CACHING_PATH_BASE = `${MOBIFY_PATH}/caching`;
+const BUNDLE_PATH_BASE = `${MOBIFY_PATH}/bundle`;
+const proxyBasePath = PROXY_PATH_BASE;
+const bundleBasePath = BUNDLE_PATH_BASE;
+const X_HEADERS_TO_REMOVE_ORIGIN = [
+    'x-api-key',
+    'x-apigateway-event',
+    'x-apigateway-context',
+    'x-mobify-access-key',
+    'x-sfdc-access-control',
+];
+export const X_MOBIFY_REQUEST_CLASS = 'x-mobify-request-class';
+export const X_MOBIFY_QUERYSTRING = 'x-mobify-querystring';
+export const X_MOBIFY_REQUEST_PROCESSOR_LOCAL = 'x-mobify-rp-local';
+const CONTENT_TYPE = 'content-type';
+const NO_CACHE = 'max-age=0, nocache, nostore, must-revalidate';
+/**
+ * Checks if a URL is for a bundle or proxy path that should be skipped by request processing.
+ *
+ * @param url - The URL to check
+ * @returns True if the URL starts with a proxy or bundle base path
+ * @private
+ */
+const _isBundleOrProxyPath = (url) => {
+    return url.startsWith(proxyBasePath) || url.startsWith(bundleBasePath);
+};
+/**
+ * Dynamically imports a request processor module if it exists.
+ *
+ * @param requestProcessorPath - The file path to the request processor module
+ * @returns The default export of the module, or null if the file doesn't exist
+ * @private
+ */
+const _getRequestProcessor = async (requestProcessorPath) => {
+    if (requestProcessorPath && fs.existsSync(requestProcessorPath)) {
+        const module = await import(requestProcessorPath);
+        return module;
+    }
+    return null;
+};
+/**
+ * Retrieves request processor parameters from environment variables with defaults.
+ *
+ * This function reads environment variables to determine the application hostname,
+ * deployment target, and environment. It provides sensible defaults for local development.
+ *
+ * @returns Object containing appHostname, deployTarget, and environment
+ * @private
+ */
+const getRequestProcessorParameters = () => {
+    return {
+        appHostname: process.env.EXTERNAL_DOMAIN_NAME || 'localhost:2401',
+        deployTarget: process.env.DEPLOY_TARGET || 'local-target',
+        environment: process.env.ENVIRONMENT || 'development',
+    };
+};
+/**
+ * Updates the request's path and querystring, and parses the query parameters.
+ *
+ * This function updates the Express request object's originalUrl and query properties.
+ * It handles both cases where a querystring is present and where it's not. For Express 5
+ * compatibility, it uses Object.defineProperty to update the query object since direct
+ * modification is no longer allowed.
+ *
+ * @param req - Express request object to update
+ * @param updatedPath - The new path to set
+ * @param updatedQuerystring - The new querystring (optional, if undefined the querystring is removed)
+ * @private
+ */
+const updatePathAndQueryString = (req, updatedPath, updatedQuerystring) => {
+    let newQuery = {};
+    if (updatedQuerystring) {
+        newQuery = qs.parse(updatedQuerystring);
+        req.originalUrl = `${updatedPath}?${updatedQuerystring}`;
+    }
+    else {
+        req.originalUrl = updatedPath;
+    }
+    // Express 5 no longer allows direct modification of the query property
+    Object.defineProperty(req, 'query', {
+        value: { ...newQuery },
+        writable: true,
+        enumerable: true,
+        configurable: true,
+    });
+};
+/**
+ * Removes internal MRT headers and API Gateway headers from the request.
+ *
+ * This function cleans up headers that should not be forwarded to downstream services.
+ * It removes API Gateway-specific headers and internal MRT headers. When called from
+ * the cleanup middleware, it also removes the X_MOBIFY_REQUEST_PROCESSOR_LOCAL header
+ * to indicate that cleanup has been performed.
+ *
+ * @param req - Express request object to clean up
+ * @param cleanupLocalRequestProcessorHeader - If true, removes X_MOBIFY_REQUEST_PROCESSOR_LOCAL header
+ * @private
+ */
+const cleanUpHeaders = (req, cleanupLocalRequestProcessorHeader = false) => {
+    // If the cleanup is happening in the local request processor
+    // we don't want to remove the X_MOBIFY_REQUEST_PROCESSOR_LOCAL header
+    // because we need to not overwrite it in the cleanup middleware
+    if (cleanupLocalRequestProcessorHeader) {
+        delete req.headers[X_MOBIFY_REQUEST_PROCESSOR_LOCAL];
+    }
+    X_HEADERS_TO_REMOVE_ORIGIN.forEach((key) => {
+        delete req.headers[key];
+    });
+};
+/**
+ * Retrieves and processes the querystring from the x-mobify-querystring header.
+ *
+ * This function checks for the x-mobify-querystring header and uses it as the
+ * definitive querystring if present and non-empty. This header is used in production
+ * environments to override the URL querystring, but is also handled in local development
+ * to allow for testing. After processing, the header is removed from the request.
+ *
+ * If the header is present but empty, or if it's not present at all, the original
+ * querystring is returned unchanged.
+ *
+ * @param req - Express request object containing the headers
+ * @param originalQuerystring - The original querystring from the URL (may be undefined)
+ * @returns The querystring to use (from header if present and non-empty, otherwise original)
+ * @private
+ */
+const getMobifyQueryString = (req, originalQuerystring) => {
+    // If there's an x-querystring header, use that as the definitive
+    // querystring. This header is used in production, not in local dev,
+    // but we always handle it here to allow for testing.
+    let updatedQuerystring = originalQuerystring;
+    const xQueryString = req.headers[X_MOBIFY_QUERYSTRING];
+    if (xQueryString && xQueryString !== '') {
+        updatedQuerystring = xQueryString;
+    }
+    delete req.headers[X_MOBIFY_QUERYSTRING];
+    return updatedQuerystring;
+};
+/**
+ * Creates a middleware function that processes incoming requests using a custom request processor.
+ *
+ * This middleware handles:
+ * - Skipping processing for proxy and bundle paths
+ * - Loading and executing custom request processors
+ * - Processing custom query strings from headers
+ * - Removing API Gateway headers
+ * - Enforcing HTTP method restrictions for root path
+ * - Updating request paths and query strings when paths change
+ *
+ * @param requestProcessorPath - Path to the request processor module file
+ * @param proxyConfigs - Array of proxy configurations
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * const middleware = createMRTRequestProcessorMiddleware(
+ *   '/path/to/processor.js',
+ *   [{ host: 'https://api.example.com', path: 'api' }]
+ * );
+ * app.use(middleware);
+ * ```
+ */
+export const createMRTRequestProcessorMiddleware = (requestProcessorPath, proxyConfigs) => {
+    const processIncomingRequest = async (req, res) => {
+        // If the request is for a proxy or bundle path, do nothing
+        if (_isBundleOrProxyPath(req.originalUrl)) {
+            return;
+        }
+        const requestProcessor = await _getRequestProcessor(requestProcessorPath);
+        const originalQuerystring = req.originalUrl.split('?')[1];
+        // If there's no querystring the value will be undefined
+        // but TypeScript will complain if we don't explicitly set it to undefined.
+        let updatedQuerystring = originalQuerystring || undefined;
+        let updatedPath = req.originalUrl.split('?')[0];
+        updatedQuerystring = getMobifyQueryString(req, updatedQuerystring);
+        if (requestProcessor) {
+            // Allow the processor to handle this request. Because this code
+            // runs only in the local development server, we intentionally do
+            // not swallow errors - we want them to happen and show up on the
+            // console because that's how developers can test the processor.
+            const headers = new Headers(req.headers, 'http');
+            const { appHostname, deployTarget, environment } = getRequestProcessorParameters();
+            const processed = requestProcessor.processRequest({
+                headers,
+                path: req.path,
+                querystring: updatedQuerystring,
+                getRequestClass: () => headers.getHeader(X_MOBIFY_REQUEST_CLASS),
+                setRequestClass: (value) => headers.setHeader(X_MOBIFY_REQUEST_CLASS, value),
+                // This matches the set of parameters passed in the
+                // Lambda@Edge context.
+                parameters: {
+                    deployTarget,
+                    appHostname,
+                    proxyConfigs: proxyConfigs || [],
+                    environment,
+                },
+            });
+            // Aid debugging by checking the return value
+            console.assert(processed && 'path' in processed && 'querystring' in processed, 'Expected processRequest to return an object with ' +
+                '"path" and "querystring" properties, ' +
+                `but got ${JSON.stringify(processed, null, 2)}`);
+            // Update the request.
+            updatedQuerystring = processed.querystring;
+            updatedPath = processed.path;
+            if (headers.modified) {
+                req.headers = headers.toObject();
+            }
+        }
+        // Update the request.
+        if (updatedQuerystring !== originalQuerystring) {
+            updatePathAndQueryString(req, updatedPath, updatedQuerystring);
+        }
+        // Get the request class and store it for general use. We
+        // must do this AFTER the request-processor, because that's
+        // what may set the request class.
+        res.locals.requestClass = req.headers[X_MOBIFY_REQUEST_CLASS];
+        req.headers[X_MOBIFY_REQUEST_PROCESSOR_LOCAL] = 'true'; // Mark the request as processed by the request processor
+    };
+    const ssrRequestProcessorMiddleware = (req, res, next) => {
+        // If the path is /, we enforce that the only methods
+        // allowed are GET, HEAD or OPTIONS. This is a restriction
+        // imposed by API Gateway: we enforce it here so that the
+        // local dev server has the same behaviour.
+        if (req.path === '/' && !['GET', 'HEAD', 'OPTIONS'].includes(req.method)) {
+            res.sendStatus(405);
+            return;
+        }
+        // Apply custom query parameter parsing and forward errors via next()
+        processIncomingRequest(req, res)
+            .then(() => {
+            // Strip out API Gateway headers from the incoming request. We
+            // do that now so that the rest of the code don't have to deal
+            // with these headers, which can be large and may be accidentally
+            // forwarded to other servers.
+            cleanUpHeaders(req, false);
+            // Hand off to the next middleware
+            next();
+        })
+            .catch((err) => {
+            next(err);
+        });
+    };
+    return ssrRequestProcessorMiddleware;
+};
+/**
+ * Creates proxy middleware functions for the specified proxy configurations.
+ *
+ * This function creates Express middleware functions that handle proxying requests
+ * to external services. It can optionally create both regular proxy and caching
+ * proxy middlewares for each configuration. The app hostname is automatically
+ * retrieved from environment variables (EXTERNAL_DOMAIN_NAME or defaults to 'localhost:2401').
+ *
+ * @param proxyConfigs - Array of proxy configurations
+ * @param appProtocol - The protocol to use for the app (defaults to 'http')
+ * @param includeCaching - Whether to include caching proxy middlewares (defaults to false)
+ * @returns Array of proxy middleware results with their paths
+ *
+ * @example
+ * ```typescript
+ * const proxyMiddlewares = createMRTProxyMiddlewares(
+ *   [{ host: 'https://api.example.com', path: 'api' }],
+ *   'https',
+ *   true // Include caching middlewares
+ * );
+ *
+ * proxyMiddlewares.forEach(({ fn, path }) => {
+ *   app.use(path, fn);
+ * });
+ * ```
+ */
+export const createMRTProxyMiddlewares = (proxyConfigs, appProtocol = 'http', includeCaching = false, createProxyFn) => {
+    if (!proxyConfigs) {
+        return [];
+    }
+    const { appHostname } = getRequestProcessorParameters();
+    const proxies = configureProxying(proxyConfigs, appHostname, appProtocol, createProxyFn);
+    const middlewares = [];
+    proxies.forEach((proxy) => {
+        const proxyPath = `${PROXY_PATH_BASE}/${proxy.path}`;
+        const cachingProxyPath = `${CACHING_PATH_BASE}/${proxy.path}`;
+        middlewares.push({ fn: proxy.fn, path: proxyPath });
+        if (includeCaching) {
+            middlewares.push({ fn: proxy.fn, path: cachingProxyPath });
+        }
+    });
+    return middlewares;
+};
+/**
+ * Sets appropriate HTTP headers for local asset files.
+ *
+ * This function sets content-type, caching, and other headers for static assets
+ * served from the local filesystem. It uses the file's modification time for
+ * ETag and Last-Modified headers, and sets no-cache directives for local assets.
+ *
+ * @param res - Express response object
+ * @param assetPath - Path to the asset file
+ *
+ * @example
+ * ```typescript
+ * app.use('/static', express.static('public', {
+ *   setHeaders: setLocalAssetHeaders
+ * }));
+ * ```
+ */
+export const setLocalAssetHeaders = (res, assetPath) => {
+    const base = path.basename(assetPath);
+    const contentType = mimeTypes.lookup(base) || 'application/octet-stream';
+    res.set(CONTENT_TYPE, contentType);
+    // Stat the file and return the last-modified Date
+    // in RFC1123 format. Also use that value as the ETag
+    // and Last-Modified
+    const mtime = fs.statSync(assetPath).mtime;
+    const mtimeRFC1123 = mtime.toUTCString();
+    res.set('date', mtimeRFC1123);
+    res.set('last-modified', mtimeRFC1123);
+    res.set('etag', mtime.getTime().toString());
+    // We don't cache local bundle assets
+    res.set('cache-control', NO_CACHE);
+};
+/**
+ * Creates an Express static middleware configured for MRT asset serving.
+ *
+ * This function creates a static file serving middleware with MRT-specific
+ * configurations including custom header setting and security options.
+ *
+ * @param staticAssetDir - Directory path containing static assets
+ * @returns Express static middleware function
+ *
+ * @example
+ * ```typescript
+ * const staticMiddleware = createMRTStaticAssetServingMiddleware('/path/to/assets');
+ * app.use('/static', staticMiddleware);
+ * ```
+ */
+export const createMRTStaticAssetServingMiddleware = (staticAssetDir) => {
+    return express.static(staticAssetDir, {
+        dotfiles: 'deny',
+        setHeaders: setLocalAssetHeaders,
+        fallthrough: false,
+    });
+};
+/**
+ * Creates a common middleware function that sets the host header based on environment variables.
+ *
+ * The host header is set to EXTERNAL_DOMAIN_NAME if available, otherwise defaults to 'localhost:2401'.
+ * Use this middleware in all environments (local and deployed), at the top of your middleware stack.
+ *
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * const middleware = createMRTCommonMiddleware();
+ * app.use(middleware);
+ * ```
+ */
+export const createMRTCommonMiddleware = () => {
+    return (req, res, next) => {
+        req.headers.host = process.env.EXTERNAL_DOMAIN_NAME || 'localhost:2401';
+        next();
+    };
+};
+/**
+ * Creates a cleanup middleware function that removes internal headers and cleans up request state.
+ *
+ * This middleware performs cleanup operations on requests:
+ * - Removes internal MRT headers (X_MOBIFY_REQUEST_PROCESSOR_LOCAL, X_MOBIFY_QUERYSTRING)
+ * - Removes API Gateway headers that shouldn't be forwarded
+ * - Optionally updates the path and querystring if the request wasn't processed by the request processor
+ *
+ * Use this middleware in all environments (local and deployed), at the end of the middleware chain,
+ * to ensure all internal headers are removed before the request is handled by the application.
+ *
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * const cleanupMiddleware = createMRTCleanUpMiddleware();
+ * app.use(cleanupMiddleware);
+ * ```
+ */
+export const createMRTCleanUpMiddleware = () => {
+    return (req, res, next) => {
+        if (!req.headers[X_MOBIFY_REQUEST_PROCESSOR_LOCAL]) {
+            const originalQuerystring = req.originalUrl.split('?')[1] || undefined;
+            const updatedQuerystring = getMobifyQueryString(req, originalQuerystring);
+            const updatedPath = req.originalUrl.split('?')[0];
+            updatePathAndQueryString(req, updatedPath, updatedQuerystring);
+        }
+        cleanUpHeaders(req, true);
+        next();
+    };
+};
+//# sourceMappingURL=middleware.js.map

package/dist/cjs/middleware/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../../src/middleware/middleware.ts"],"names":[],"mappings":"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"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/streaming/create-lambda-adapter.d.ts

@@ -0,0 +1,68 @@
+import { type ZlibOptions, type BrotliOptions, type ZstdOptions } from 'node:zlib';
+import type { APIGatewayProxyEvent, Context } from 'aws-lambda';
+import type { Express, Request, Response } from 'express';
+import type { Writable } from 'stream';
+interface ExpressRequest extends Request {
+    apiGateway?: {
+        event: APIGatewayProxyEvent;
+        context: Context;
+    };
+}
+interface ExpressResponse extends Response {
+    flushable?: boolean;
+}
+/**
+ * Configuration options for response compression.
+ *
+ * @property enabled - Whether compression is enabled. Set to false to disable compression entirely.
+ *                     Defaults to true (compression enabled).
+ * @property encoding - The compression encoding to use ('br', 'zstd', 'gzip', 'deflate').
+ *                      If not specified, the best encoding will be negotiated based on Accept-Encoding header.
+ * @property options  - Compression library options. This can include any of the options accepted by
+ *                      zlib, Brotli, or Zstd, as defined in the zlib library, and will be passed
+ *                      directly to the corresponding compression library.
+ */
+export interface CompressionConfig {
+    enabled: boolean;
+    encoding?: 'br' | 'zstd' | 'gzip' | 'deflate';
+    options?: ZlibOptions | BrotliOptions | ZstdOptions;
+}
+type AsyncHandlerFunction = (event: APIGatewayProxyEvent, context: Context) => Promise<void>;
+/**
+ * Creates a Lambda Adapter that wraps an Express app and supports response streaming
+ * for API Gateway v1 proxy integration using AWS Lambda response streaming
+ *
+ * @param app - Express application instance
+ * @param responseStream - AWS Lambda response stream
+ * @param compressionConfig - Optional compression configuration
+ * @returns Lambda handler function
+ */
+export declare function createStreamingLambdaAdapter(app: Express, responseStream: Writable, compressionConfig?: CompressionConfig): AsyncHandlerFunction;
+/**
+ * Converts API Gateway event to Express-compatible request object
+ * Creates a proper IncomingMessage-like object with stream properties
+ */
+export declare function createExpressRequest(event: APIGatewayProxyEvent, context: Context): ExpressRequest;
+/**
+ * Creates Express-compatible response object that properly extends ServerResponse
+ *
+ * This function creates a response object that:
+ * - Supports AWS Lambda response streaming via HttpResponseStream
+ * - Automatically compresses responses based on Accept-Encoding header
+ * - Uses negotiator to select the best available encoding (br, zstd if available, gzip, deflate)
+ * - Uses compressible package to determine if content should be compressed
+ *
+ * Compression flow:
+ * 1. Check Accept-Encoding header and select best encoding
+ * 2. Create HttpResponseStream with metadata
+ * 3. If compression is applicable, create compression stream and pipe to httpResponseStream
+ * 4. Write data to compression stream (or httpResponseStream if no compression)
+ * 5. End compression stream, which automatically ends httpResponseStream
+ *
+ * @param responseStream - The AWS Lambda response stream
+ * @param method - The HTTP method (GET, POST, etc.)
+ * @param request - Optional Express request object (used to check Accept-Encoding header)
+ * @returns Express-compatible response object
+ */
+export declare function createExpressResponse(responseStream: Writable, event: APIGatewayProxyEvent, context: Context, request?: ExpressRequest, compressionConfig?: CompressionConfig): ExpressResponse;
+export {};