@63klabs/cache-data 1.3.9 → 1.3.11

package/src/lib/tools/ClientRequest.class.js

@@ -401,6 +401,7 @@ class ClientRequest extends RequestInfo {
 	
 	/* Validation system */
 	#validationMatchers = {};
+	#validationReason = { isValid: true, statusCode: 200, messages: [] };
 
 	/* The request data */
 	#props = {};
@@ -470,6 +471,10 @@ class ClientRequest extends RequestInfo {
 			bodyParameters: {},
 			bodyPayload: this.#event?.body || null, // from body
 			client: {
+				ip: this.getClientIp(),
+				userAgent: this.getClientUserAgent(),
+				origin: this.getClientOrigin(),
+				referrer: this.getClientReferrer(),
 				isAuthenticated: this.isAuthenticated(),
 				isGuest: this.isGuest(),
 				authorizations: this.getAuthorizations(),
@@ -698,7 +703,7 @@ class ClientRequest extends RequestInfo {
 	 * Parameter validations
 	 * @returns {{
 	 * 	pathParameters?: object,
-	 * 	queryParameters?: object,
+	 * 	queryStringParameters?: object,
 	 * 	headerParameters?: object,
 	 * 	cookieParameters?: object,
 	 * 	bodyParameters?: object
@@ -755,25 +760,129 @@ class ClientRequest extends RequestInfo {
 	 */
 	#validate() {
 	
-		let valid = false;
+		const reasons = [];
+		let statusCode = 200;
+
+		// Referrer check
+		const referrerValid = this.isAuthorizedReferrer();
+		if (!referrerValid) {
+			reasons.push("Forbidden");
+			statusCode = this.#upgradeStatusCode(statusCode, 403);
+		}
+
+		// Authentication check
+		const authFailed = this.hasNoAuthorization();
+		if (authFailed) {
+			reasons.push("Unauthorized");
+			statusCode = this.#upgradeStatusCode(statusCode, 401);
+		}
+
+		// Parameter checks - collect invalid parameter names from each
+		const pathResult = this.#hasValidPathParameters();
+		const queryResult = this.#hasValidQueryStringParameters();
+		const headerResult = this.#hasValidHeaderParameters();
+		const cookieResult = this.#hasValidCookieParameters();
+		const bodyResult = this.#hasValidBodyParameters();
+
+		// Collect invalid parameter messages
+		const paramResults = [pathResult, queryResult, headerResult, cookieResult, bodyResult];
+		for (const result of paramResults) {
+			if (result.invalidParams) {
+				for (const paramName of result.invalidParams) {
+					reasons.push(`Invalid parameter: ${paramName}`);
+					statusCode = this.#upgradeStatusCode(statusCode, 400);
+				}
+			}
+		}
 
-		// add your additional validations here
-		valid = this.isAuthorizedReferrer() && this.#hasValidPathParameters() && this.#hasValidQueryStringParameters() && this.#hasValidHeaderParameters() && this.#hasValidCookieParameters() && this.#hasValidBodyParameters();
+		// Handle invalid JSON body
+		if (bodyResult.invalidBody) {
+			reasons.push("Invalid request body");
+			statusCode = this.#upgradeStatusCode(statusCode, 400);
+		}
 
-		// set the variable
+		// Compute combined valid boolean from all check results
+		const valid = referrerValid && !authFailed
+			&& pathResult.isValid && queryResult.isValid && headerResult.isValid
+			&& cookieResult.isValid && bodyResult.isValid;
+
+		// Preserve backwards compatibility
 		super._isValid = valid;
 
+		// Populate validation reason
+		this.#validationReason = {
+			isValid: valid,
+			statusCode: valid ? 200 : statusCode,
+			messages: valid ? [] : reasons
+		};
+
+	};
+
+	/**
+	 * Returns the higher-priority HTTP status code between two candidates.
+	 * Priority order: 401 > 403 > 400 > 200.
+	 *
+	 * @private
+	 * @param {number} current - The current status code
+	 * @param {number} candidate - The candidate status code to compare
+	 * @returns {number} The status code with higher priority
+	 */
+	#upgradeStatusCode(current, candidate) {
+		const priority = { 401: 3, 403: 2, 400: 1, 200: 0 };
+		return (priority[candidate] || 0) > (priority[current] || 0) ? candidate : current;
 	};
 
+	/**
+	 * Returns a structured validation result object describing why the request
+	 * passed or failed validation. The object includes the validation status,
+	 * an appropriate HTTP status code, and descriptive messages identifying
+	 * each failure.
+	 * 
+	 * A new object is returned on each call to prevent external mutation of
+	 * internal state.
+	 * 
+	 * @returns {{ isValid: boolean, statusCode: number, messages: Array<string> }}
+	 *   A new object on each call containing:
+	 *   - isValid: whether the request passed all validation checks
+	 *   - statusCode: the appropriate HTTP status code (200, 400, 401, or 403)
+	 *   - messages: array of descriptive failure messages (empty when valid)
+	 * @example
+	 * // Valid request
+	 * const reason = clientRequest.getValidationReason();
+	 * // { isValid: true, statusCode: 200, messages: [] }
+	 *
+	 * @example
+	 * // Invalid request with bad parameters
+	 * const reason = clientRequest.getValidationReason();
+	 * // { isValid: false, statusCode: 400, messages: ["Invalid parameter: limit"] }
+	 */
+	getValidationReason() {
+		return {
+			isValid: this.#validationReason.isValid,
+			statusCode: this.#validationReason.statusCode,
+			messages: [...this.#validationReason.messages]
+		};
+	}
+
 	/**
 	 * Validate parameters using ValidationMatcher and ValidationExecutor.
 	 * 
 	 * This method implements the core parameter validation logic:
 	 * 1. Uses ValidationMatcher to find the best matching validation rule (4-tier priority)
 	 * 2. Uses ValidationExecutor to execute validation with appropriate interface (single or multi-parameter)
-	 * 3. Extracts validated parameters and returns them
+	 * 3. Extracts ALL validated parameters specified in the matching rule and returns them
 	 * 4. Respects excludeParamsWithNoValidationMatch flag (default: true)
 	 * 
+	 * When a validation rule matches and validation passes, ALL parameters specified in rule.params
+	 * are extracted from clientParameters and included in the returned params object. This ensures
+	 * that multi-parameter validation rules (e.g., validating query?param1,param2 together) correctly
+	 * extract all validated parameters, not just the one that triggered the rule match.
+	 * 
+	 * For single-parameter validation with multi-placeholder routes (e.g., users/{userId}/posts/{id}):
+	 * - ValidationMatcher returns validateParam field indicating which parameter to validate
+	 * - ValidationExecutor validates only that parameter with single-parameter interface
+	 * - This method extracts ALL parameters from rule.params array (e.g., both userId and id)
+	 * 
 	 * @private
 	 * @param {Object} paramValidations - Parameter validation configuration (may include BY_ROUTE, BY_METHOD, and global validations)
 	 * @param {Object} clientParameters - Parameters from the request (path, query, header, or cookie parameters)
@@ -791,12 +900,25 @@ class ClientRequest extends RequestInfo {
 
 		let rValue = {
 			isValid: true,
-			params: {}
+			params: {},
+			invalidParams: []
 		}
 	
-		if (clientParameters && paramValidations) {
+		if (clientParameters) {
 			// >! Check excludeParamsWithNoValidationMatch flag (default: true)
 			const excludeUnmatched = ClientRequest.#validations.parameters?.excludeParamsWithNoValidationMatch !== false;
+
+			// >! When no validation rules exist for this parameter type,
+			// >! pass through all parameters if excludeUnmatched is false
+			if (!paramValidations) {
+				if (!excludeUnmatched) {
+					rValue.params = { ...clientParameters };
+				}
+				return rValue;
+			}
+			
+			// >! Track which parameters have been validated to avoid duplicate validation
+			const validatedParams = new Set();
 			
 			// >! Create normalized parameter map for validation execution
 			// >! Include ALL parameter types so multi-parameter validations can access them
@@ -841,12 +963,20 @@ class ClientRequest extends RequestInfo {
 				normalizedParams[normalizedKey] = value;
 			}
 			
+			// >! Collect valid params separately so we can clear them if any fail
+			const collectedParams = {};
+
 			// Use a for...of loop instead of forEach for better control flow
 			for (const [key, value] of Object.entries(clientParameters)) {
 				// >! Preserve existing parameter key normalization
 				const paramKey = key.replace(/^\/|\/$/g, '');
 				const paramValue = value;
 				
+				// >! Skip parameters that have already been validated
+				if (validatedParams.has(paramKey)) {
+					continue;
+				}
+				
 				// >! Use ValidationMatcher to find the best matching validation rule
 				const rule = validationMatcher.findValidationRule(paramKey);
 				
@@ -856,22 +986,41 @@ class ClientRequest extends RequestInfo {
 					const isValid = ValidationExecutor.execute(rule.validate, rule.params, normalizedParams);
 					
 					if (isValid) {
-						rValue.params[paramKey] = paramValue;
+						// >! Extract ALL parameters specified in rule.params when validation passes
+						// >! This fixes the bug where only the current paramKey was added
+						for (const ruleParamName of rule.params) {
+							// >! Find the parameter value in clientParameters
+							// >! Use normalized key matching to handle case differences
+							const normalizedRuleParam = ruleParamName.replace(/^\/|\/$/g, '');
+							
+							// >! Search for matching parameter in clientParameters
+							for (const [clientKey, clientValue] of Object.entries(clientParameters)) {
+								const normalizedClientKey = clientKey.replace(/^\/|\/$/g, '');
+								
+								if (normalizedClientKey === normalizedRuleParam) {
+									collectedParams[clientKey] = clientValue;
+									// >! Mark this parameter as validated to avoid duplicate validation
+									validatedParams.add(normalizedClientKey);
+									break;
+								}
+							}
+						}
 					} else {
 						// >! Maintain existing logging for invalid parameters
 						DebugAndLog.warn(`Invalid parameter: ${paramKey} = ${paramValue}`);
 						rValue.isValid = false;
-						rValue.params = {};
-						// >! Ensure early exit on validation failure
-						return rValue;
+						rValue.invalidParams.push(paramKey);
 					}
 				} else if (!excludeUnmatched) {
 					// No validation rule found, but excludeUnmatched is false
 					// Include parameter without validation
-					rValue.params[paramKey] = paramValue;
+					collectedParams[paramKey] = paramValue;
 				}
 				// If excludeUnmatched is true and no rule found, skip parameter (existing behavior)
 			}
+
+			// >! If any parameter failed, clear params (preserves existing behavior)
+			rValue.params = rValue.isValid ? collectedParams : {};
 		}	
 		return rValue;
 	}
@@ -889,13 +1038,13 @@ class ClientRequest extends RequestInfo {
 	 * const isValid = #hasValidPathParameters();
 	 */
 	#hasValidPathParameters() {
-		const { isValid, params } = this.#hasValidParameters(
+		const { isValid, params, invalidParams } = this.#hasValidParameters(
 			ClientRequest.getParameterValidations()?.pathParameters,
 			this.#event?.pathParameters,
 			this.#validationMatchers.pathParameters
 		);
 		this.#props.pathParameters = params;
-		return isValid;
+		return { isValid, invalidParams };
 	}
 
 	/**
@@ -923,13 +1072,13 @@ class ClientRequest extends RequestInfo {
 		const paramValidations = ClientRequest.getParameterValidations();
 		const queryValidations = paramValidations?.queryStringParameters || paramValidations?.queryParameters;
 		
-		const { isValid, params } = this.#hasValidParameters(
+		const { isValid, params, invalidParams } = this.#hasValidParameters(
 			queryValidations,
 			qs,
 			this.#validationMatchers.queryStringParameters
 		);
 		this.#props.queryStringParameters = params;
-		return isValid;
+		return { isValid, invalidParams };
 	}
 
 	/**
@@ -977,23 +1126,23 @@ class ClientRequest extends RequestInfo {
 				const camelCaseKey = key.toLowerCase().replace(/-([a-z])/g, (g) => g[1].toUpperCase());
 				headers[camelCaseKey] = this.#event.headers[key];
 			}
-			const { isValid, params } = this.#hasValidParameters(
+			const { isValid, params, invalidParams } = this.#hasValidParameters(
 				ClientRequest.getParameterValidations()?.headerParameters,
 				headers,
 				this.#validationMatchers.headerParameters
 			);
 			this.#props.headerParameters = params;
-			return isValid;
+			return { isValid, invalidParams };
 		}
 
 	#hasValidCookieParameters() {
-		const { isValid, params } = this.#hasValidParameters(
+		const { isValid, params, invalidParams } = this.#hasValidParameters(
 			ClientRequest.getParameterValidations()?.cookieParameters,
 			this.#event?.cookie,
 			this.#validationMatchers.cookieParameters
 		);
 		this.#props.cookieParameters = params;
-		return isValid;
+		return { isValid, invalidParams };
 	}
 
 	/**
@@ -1028,12 +1177,12 @@ class ClientRequest extends RequestInfo {
 					error?.stack
 				);
 				this.#props.bodyParameters = {};
-				return false;
+				return { isValid: false, invalidParams: [], invalidBody: true };
 			}
 		}
 
 		// >! Use existing validation framework with body validation matcher
-		const { isValid, params } = this.#hasValidParameters(
+		const { isValid, params, invalidParams } = this.#hasValidParameters(
 			ClientRequest.getParameterValidations()?.bodyParameters,
 			bodyObject,
 			this.#validationMatchers.bodyParameters
@@ -1041,7 +1190,7 @@ class ClientRequest extends RequestInfo {
 
 		// >! Store validated parameters
 		this.#props.bodyParameters = params;
-		return isValid;
+		return { isValid, invalidParams };
 	}
 
 
@@ -1251,8 +1400,16 @@ class ClientRequest extends RequestInfo {
 	/**
 	 * Get the _processed_ request properties. These are the properties that
 	 * the ClientRequest object took from the event sent to Lambda, validated,
-	 * supplemented, and makes available to controllers. 
-	 * @returns {{ method: string, path: string, pathArray: string[], resource: string, resourceArray[], pathParameters: {}, queryStringParameters: {}, headerParameters: {}, cookieParameters: {}, bodyPayload: string, client: {isAuthenticated: boolean, isGuest: boolean, authorizations: string[], roles: string[]}, deadline: number, calcMsToDeadline: number}
+	 * supplemented, and makes available to controllers.
+	 * 
+	 * Note When accessed behind CloudFront:
+	 * To ensure the user agent is passed along to API Gateway, use the AWS 
+	 * managed Origin Request Policy named AllViewerExceptHostHeader. This 
+	 * forwards the User-Agent along with most other viewer headers while 
+	 * maintaining the correct Host header required for API Gateway to route 
+	 * the request properly.
+	 *
+	 * @returns {{ method: string, path: string, pathArray: string[], resource: string, resourceArray: string[], pathParameters: {}, queryStringParameters: {}, headerParameters: {}, cookieParameters: {}, bodyParameters: {}, bodyPayload: string, client: {ip: string, userAgent: string, origin: string, referrer: string, isAuthenticated: boolean, isGuest: boolean, authorizations: string[], roles: string[]}, deadline: number, calcMsToDeadline: function}
 	 */
 	getProps() {
 		return this.#props;

package/src/lib/tools/Connections.classes.js

@@ -32,7 +32,7 @@ const { safeClone } = require('./utils');
  * 
  * // Use with endpoint requests
  * const dbConn = connections.get('database');
- * const result = await endpoint.get(dbConn);
+ * const result = await endpoint.send(dbConn);
  */
 class Connections {
 	
@@ -132,7 +132,7 @@ class Connections {
  * The Connection object provides the base for requests but does not carry
  * the request. myConnection.get() will return an object (associative array) 
  * that can then be used to generate and submit a request to a DAO class or 
- * APIRequest object.
+ * ApiRequest object.
  * You can store and manage multiple connections using the Connections object.
  * @example
  * // Create a simple connection
@@ -145,7 +145,7 @@ class Connections {
  * 
  * // Get connection object for use with endpoint
  * const connObj = apiConnection.get();
- * const users = await endpoint.get(connObj);
+ * const users = await endpoint.send(connObj);
  * 
  * @example
  * // Create connection with authentication
@@ -581,7 +581,7 @@ class ConnectionAuthentication {
  * request.addParameter('page', 1);
  * 
  * // Make the request
- * const result = await endpoint.get(request);
+ * const result = await endpoint.send(request);
  * 
  * @example
  * // Build a request dynamically in a DAO
@@ -597,7 +597,7 @@ class ConnectionAuthentication {
  *       'Content-Type': 'application/json'
  *     });
  *     
- *     return await endpoint.get(request);
+ *     return await endpoint.send(request);
  *   }
  * }
  */

package/src/lib/tools/RequestInfo.class.js

@@ -130,6 +130,12 @@ class RequestInfo {
 
 	/**
 	 * User Agent of client request
+	 * Note When accessed behind CloudFront:
+	 * To ensure the user agent is passed along to API Gateway, use the AWS 
+	 * managed Origin Request Policy named AllViewerExceptHostHeader. This 
+	 * forwards the User-Agent along with most other viewer headers while 
+	 * maintaining the correct Host header required for API Gateway to route 
+	 * the request properly.
 	 * @returns {string} The user agent string supplied by the client request
 	 */
 	getClientUserAgent() {
@@ -259,9 +265,25 @@ class RequestInfo {
 
 
 	/**
-	 * Obtain lambda event request details for logging
-	 * @param {*} event 
-	 * @returns Information about the requesting client including IP and user agent
+	 * Obtain lambda event request details for logging.
+	 * Parses the API Gateway event to extract client information including IP,
+	 * user agent, origin, referrer, headers, and query parameters.
+	 * 
+	 * For `client.ip`, the `x-forwarded-for` header is preferred over
+	 * `identity.sourceIp`. When `x-forwarded-for` is present and non-empty,
+	 * the first IP from the comma-separated list is used (trimmed). This
+	 * ensures the original client IP is returned when behind a proxy such
+	 * as CloudFront. Falls back to `identity.sourceIp` when the header is
+	 * absent or empty.
+	 * 
+	 * For `client.userAgent`, the `user-agent` header is preferred over
+	 * `identity.userAgent`. When the header is present and non-empty, its
+	 * value is used directly. This ensures the original client user agent
+	 * is returned instead of a proxy identifier (e.g. "Amazon CloudFront").
+	 * Falls back to `identity.userAgent` when the header is absent or empty.
+	 * 
+	 * @param {object} event - API Gateway Lambda event object
+	 * @returns {{ip: string|null, userAgent: string|null, origin: string|null, referrer: string|null, ifModifiedSince: string|null, ifNoneMatch: string|null, accept: string|null, headers: object, parameters: object, body: string|null}} Client request information
 	 */
 	_clientRequestInfo (event) {
 
@@ -292,11 +314,24 @@ class RequestInfo {
 			client.ip = identity.sourceIp;
 		}
 
+		// if x-forwarded-for header is present, prefer it over identity.sourceIp (first IP in the list is the original client)
+		if ( "x-forwarded-for" in headers && headers["x-forwarded-for"] !== null && headers["x-forwarded-for"] !== "" ) {
+			let firstIp = headers["x-forwarded-for"].split(",")[0].trim();
+			if ( firstIp !== "" ) {
+				client.ip = firstIp;
+			}
+		}
+
 		// if there is a user-agent header, set it
 		if ( "userAgent" in identity && identity.userAgent !== null ) {
 			client.userAgent = identity.userAgent;
 		}
 
+		// if user-agent header is present, prefer it over identity.userAgent (original client user agent)
+		if ( "user-agent" in headers && headers["user-agent"] !== null && headers["user-agent"] !== "" ) {
+			client.userAgent = headers["user-agent"];
+		}
+
 		// if there is an origin header, set it
 		if ( headers?.origin) {
 			client.origin = headers.origin;

package/src/lib/tools/Response.class.js

@@ -525,6 +525,31 @@ class Response {
 		}
 	};
 
+	/**
+	 * Sets a message or messages property on the JSON response body.
+	 * If the body is not a JSON object, this method is a no-op.
+	 * Does not alter the status code or headers.
+	 *
+	 * @param {string|Array<string>} message - A single message string or array of message strings
+	 * @returns {void}
+	 * @example
+	 * // Single message
+	 * response.setMessage("Invalid parameter: limit");
+	 * // body becomes: { ...existingBody, message: "Invalid parameter: limit" }
+	 *
+	 * @example
+	 * // Multiple messages
+	 * response.setMessage(["Invalid parameter: limit", "Invalid parameter: offset"]);
+	 * // body becomes: { ...existingBody, messages: ["Invalid parameter: limit", "Invalid parameter: offset"] }
+	 */
+	setMessage = (message) => {
+		if (Array.isArray(message)) {
+			this.addToJsonBody({ messages: message });
+		} else {
+			this.addToJsonBody({ message: message });
+		}
+	};
+
 	/**
 	 * Converts the response to a plain object.
 	 * 

package/src/lib/tools/generic.response.html.js

@@ -1,121 +1,16 @@
-contentType = "text/html; charset=utf-8";
+const { createGenericResponseModule } = require("./generic.response");
 
-headers = {
-	"Content-Type": contentType
-};
-
-html = (title, body) => {
+const html = (title, body) => {
 	return `<html><head><title>${title}</title></head><body>${body}</body></html>`;
-}
-
-response200 = {
-	statusCode: 200,
-	headers: headers,
-	body: html("200 OK", "<p>Success</p>")
-};
-
-response400 = {
-	statusCode: 400,
-	headers: headers,
-	body: html("400 Bad Request", "<p>Bad Request</p>")
-};
-
-response401 = {
-	statusCode: 401,
-	headers: headers,
-	body: html("401 Unauthorized", "<p>Unauthorized</p>")
-};
-
-response403 = {
-	statusCode: 403,
-	headers: headers,
-	body: html("403 Forbidden", "<p>Forbidden</p>")
-};
-
-response404 = {
-	statusCode: 404,
-	headers: headers,
-	body: html("404 Not Found", "<p>Not Found</p>")
-};
-
-response405 = {
-	statusCode: 405,
-	headers: headers,
-	body: html("405 Method Not Allowed", "<p>Method Not Allowed</p>")
-};
-
-response408 = {
-	statusCode: 408,
-	headers: headers,
-	body: html("408 Request Timeout", "<p>Request Timeout</p>")
 };
 
-response418 = {
-	statusCode: 418,
-	headers: headers,
-	body: html("418 I'm a teapot", "<p>I'm a teapot</p>")
+const HTML_TITLE_MAP = {
+	200: "OK",
+	500: "Error"
 };
 
-response427 = {
-	statusCode: 427,
-	headers: headers,
-	body: html("427 Too Many Requests", "<p>Too Many Requests</p>")
-};
-
-response500 = {
-	statusCode: 500,
-	headers: headers,
-	body: html("500 Error", "<p>Internal Server Error</p>")
-};
+const htmlBodyFormatter = (statusCode, message) => html(statusCode + " " + (HTML_TITLE_MAP[statusCode] || message), "<p>" + message + "</p>");
 
-/**
- * 
- * @param {number|string} statusCode 
- * @returns {{statusCode: number, headers: object, body: Array|Object|string}}
- */
-response = function (statusCode) {
-	// convert to int
-	statusCode = parseInt(statusCode, 10);
-
-	switch (statusCode) {
-		case 200:
-			return this.response200;
-		case 400:
-			return this.response400;
-		case 401:
-			return this.response401;
-		case 403:
-			return this.response403;
-		case 404:
-			return this.response404;
-		case 405:
-			return this.response405;
-		case 408:
-			return this.response408;
-		case 418:
-			return this.response418;
-		case 427:
-			return this.response427;
-		case 500:
-			return this.response500;
-		default:
-			return this.response500;
-	}
-};
+const mod = createGenericResponseModule("text/html; charset=utf-8", htmlBodyFormatter);
 
-module.exports = {
-	contentType,
-	headers,
-	html,
-	response200,
-	response400,
-	response401,
-	response403,
-	response404,
-	response405,
-	response408,
-	response418,
-	response427,
-	response500,
-	response
-}
+module.exports = { ...mod, html };