@salesforce/mrt-utilities 0.0.1 → 0.1.1

package/dist/cjs/middleware/data-store.js

@@ -0,0 +1,124 @@
+/*
+ * 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
+ */
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient, GetCommand } from '@aws-sdk/lib-dynamodb';
+import { logMRTError } from '../utils/utils.js';
+export class DataStoreNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DataStoreNotFoundError';
+        Object.setPrototypeOf(this, DataStoreNotFoundError.prototype);
+    }
+}
+export class DataStoreServiceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DataStoreServiceError';
+        Object.setPrototypeOf(this, DataStoreServiceError.prototype);
+    }
+}
+export class DataStoreUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DataStoreUnavailableError';
+        Object.setPrototypeOf(this, DataStoreUnavailableError.prototype);
+    }
+}
+/**
+ * A class for reading entries from the data store.
+ *
+ * This class uses a singleton pattern.
+ * Use DataStore.getDataStore() to get the singleton instance.
+ */
+export class DataStore {
+    _tableName = '';
+    _ddb = null;
+    static _instance = null;
+    /** @internal Test hook: inject a document client for unit tests */
+    static _testDocumentClient = null;
+    /** @internal Test hook: inject logMRTError for unit tests */
+    static _testLogMRTError = null;
+    constructor() {
+        // Private constructor for singleton; use DataStore.getDataStore() instead.
+    }
+    /**
+     * Get or create a DynamoDB document client (for abstraction of attribute values).
+     *
+     * @private
+     * @returns The DynamoDB document client
+     * @throws {DataStoreUnavailableError} The data store is unavailable
+     */
+    getClient() {
+        if (!this.isDataStoreAvailable()) {
+            throw new DataStoreUnavailableError('The data store is unavailable.');
+        }
+        if (DataStore._testDocumentClient) {
+            this._tableName = `DataAccessLayer-${process.env.AWS_REGION}`;
+            return DataStore._testDocumentClient;
+        }
+        if (!this._ddb) {
+            this._tableName = `DataAccessLayer-${process.env.AWS_REGION}`;
+            this._ddb = DynamoDBDocumentClient.from(new DynamoDBClient({
+                region: process.env.AWS_REGION,
+            }));
+        }
+        return this._ddb;
+    }
+    /**
+     * Get or create the singleton DataStore instance.
+     *
+     * @returns The singleton DataStore instance
+     */
+    static getDataStore() {
+        if (!DataStore._instance) {
+            DataStore._instance = new DataStore();
+        }
+        return DataStore._instance;
+    }
+    /**
+     * Whether the data store can be used in the current environment.
+     *
+     * @returns true if the data store is available, false otherwise
+     */
+    isDataStoreAvailable() {
+        return Boolean(process.env.AWS_REGION && process.env.MOBIFY_PROPERTY_ID && process.env.DEPLOY_TARGET);
+    }
+    /**
+     * Fetch an entry from the data store.
+     *
+     * @param key The data store entry's key
+     * @returns An object containing the entry's key and value
+     * @throws {DataStoreUnavailableError} The data store is unavailable
+     * @throws {DataStoreNotFoundError} An entry with the given key cannot be found
+     * @throws {DataStoreServiceError} An internal error occurred
+     */
+    async getEntry(key) {
+        if (!this.isDataStoreAvailable()) {
+            throw new DataStoreUnavailableError('The data store is unavailable.');
+        }
+        const ddb = this.getClient();
+        let response;
+        try {
+            response = await ddb.send(new GetCommand({
+                TableName: this._tableName,
+                Key: {
+                    projectEnvironment: `${process.env.MOBIFY_PROPERTY_ID} ${process.env.DEPLOY_TARGET}`,
+                    key,
+                },
+            }));
+        }
+        catch (error) {
+            const logFn = DataStore._testLogMRTError ?? logMRTError;
+            logFn('data_store', error, { key, tableName: this._tableName });
+            throw new DataStoreServiceError('Data store request failed.');
+        }
+        if (!response.Item?.value) {
+            throw new DataStoreNotFoundError(`Data store entry '${key}' not found.`);
+        }
+        return { key, value: response.Item.value };
+    }
+}
+//# sourceMappingURL=data-store.js.map

package/dist/cjs/middleware/data-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-store.js","sourceRoot":"","sources":["../../../src/middleware/data-store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAC,cAAc,EAAC,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAC,sBAAsB,EAAE,UAAU,EAAwB,MAAM,uBAAuB,CAAC;AAEhG,OAAO,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAE9C,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAChE,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAC/D,CAAC;CACF;AAED,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,yBAAyB,CAAC,SAAS,CAAC,CAAC;IACnE,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,SAAS;IACZ,UAAU,GAAW,EAAE,CAAC;IACxB,IAAI,GAAkC,IAAI,CAAC;IAC3C,MAAM,CAAC,SAAS,GAAqB,IAAI,CAAC;IAElD,mEAAmE;IACnE,MAAM,CAAC,mBAAmB,GAAkC,IAAI,CAAC;IACjE,6DAA6D;IAC7D,MAAM,CAAC,gBAAgB,GAA0F,IAAI,CAAC;IAEtH;QACE,2EAA2E;IAC7E,CAAC;IAED;;;;;;OAMG;IACK,SAAS;QACf,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,CAAC;YACjC,MAAM,IAAI,yBAAyB,CAAC,gCAAgC,CAAC,CAAC;QACxE,CAAC;QAED,IAAI,SAAS,CAAC,mBAAmB,EAAE,CAAC;YAClC,IAAI,CAAC,UAAU,GAAG,mBAAmB,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC;YAC9D,OAAO,SAAS,CAAC,mBAAmB,CAAC;QACvC,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,IAAI,CAAC,UAAU,GAAG,mBAAmB,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC;YAC9D,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC,IAAI,CACrC,IAAI,cAAc,CAAC;gBACjB,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU;aAC/B,CAAC,CACH,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,YAAY;QACjB,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,CAAC;YACzB,SAAS,CAAC,SAAS,GAAG,IAAI,SAAS,EAAE,CAAC;QACxC,CAAC;QACD,OAAO,SAAS,CAAC,SAAS,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,oBAAoB;QAClB,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACxG,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,QAAQ,CAAC,GAAW;QACxB,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,CAAC;YACjC,MAAM,IAAI,yBAAyB,CAAC,gCAAgC,CAAC,CAAC;QACxE,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAC7B,IAAI,QAA0B,CAAC;QAC/B,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,GAAG,CAAC,IAAI,CACvB,IAAI,UAAU,CAAC;gBACb,SAAS,EAAE,IAAI,CAAC,UAAU;gBAC1B,GAAG,EAAE;oBACH,kBAAkB,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE;oBACpF,GAAG;iBACJ;aACF,CAAC,CACH,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,KAAK,GAAG,SAAS,CAAC,gBAAgB,IAAI,WAAW,CAAC;YACxD,KAAK,CAAC,YAAY,EAAE,KAAK,EAAE,EAAC,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,UAAU,EAAC,CAAC,CAAC;YAC9D,MAAM,IAAI,qBAAqB,CAAC,4BAA4B,CAAC,CAAC;QAChE,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;YAC1B,MAAM,IAAI,sBAAsB,CAAC,qBAAqB,GAAG,cAAc,CAAC,CAAC;QAC3E,CAAC;QAED,OAAO,EAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAC,CAAC;IAC3C,CAAC"}

package/dist/cjs/middleware/index.d.ts

@@ -0,0 +1,3 @@
+export * from './data-store.js';
+export * from './middleware.js';
+export { type ProxyConfig } from '../utils/configure-proxying.js';

package/dist/cjs/middleware/index.js

@@ -0,0 +1,8 @@
+/*
+ * 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
+ */
+export * from './data-store.js';
+export * from './middleware.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/cjs/middleware/middleware.d.ts

@@ -0,0 +1,126 @@
+import { type ProxyResult, type ProxyConfig, type CreateProxyMiddlewareFn } from '../utils/configure-proxying.js';
+import { type RequestHandler, type Response } from 'express';
+export declare const X_MOBIFY_REQUEST_CLASS = "x-mobify-request-class";
+export declare const X_MOBIFY_QUERYSTRING = "x-mobify-querystring";
+export declare const X_MOBIFY_REQUEST_PROCESSOR_LOCAL = "x-mobify-rp-local";
+/**
+ * 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 declare const createMRTRequestProcessorMiddleware: (requestProcessorPath: string | undefined, proxyConfigs: ProxyConfig[] | undefined) => RequestHandler;
+/**
+ * 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 declare const createMRTProxyMiddlewares: (proxyConfigs: ProxyConfig[], appProtocol?: string, includeCaching?: boolean, createProxyFn?: CreateProxyMiddlewareFn) => ProxyResult[];
+/**
+ * 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 declare const setLocalAssetHeaders: (res: Response, assetPath: string) => void;
+/**
+ * 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 declare const createMRTStaticAssetServingMiddleware: (staticAssetDir: string) => RequestHandler;
+/**
+ * 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 declare const createMRTCommonMiddleware: () => RequestHandler;
+/**
+ * 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 declare const createMRTCleanUpMiddleware: () => RequestHandler;