@gxp-dev/tools 2.0.6 → 2.0.8

package/runtime/mock-api/response-generator.js

@@ -0,0 +1,394 @@
+/**
+ * Response Generator
+ *
+ * Generates fake JSON data from OpenAPI/JSON Schema definitions
+ * using Faker.js for realistic values.
+ */
+
+const { faker } = require("@faker-js/faker");
+
+/**
+ * Resolve a $ref reference in the spec
+ * @param {string} ref - Reference string (e.g., "#/components/schemas/User")
+ * @param {object} spec - Full OpenAPI spec
+ * @returns {object|null} Resolved schema or null
+ */
+function resolveRef(ref, spec) {
+	if (!ref || !ref.startsWith("#/")) {
+		return null;
+	}
+
+	const parts = ref.slice(2).split("/");
+	let current = spec;
+
+	for (const part of parts) {
+		if (current && typeof current === "object" && part in current) {
+			current = current[part];
+		} else {
+			console.warn(`⚠️  Could not resolve $ref: ${ref}`);
+			return null;
+		}
+	}
+
+	return current;
+}
+
+/**
+ * Generate a value for a primitive type with optional format
+ * @param {string} type - JSON Schema type
+ * @param {string} format - Optional format hint
+ * @param {object} schema - Full schema for additional constraints
+ * @returns {*} Generated value
+ */
+function generateValue(type, format, schema = {}) {
+	// Handle enums first
+	if (schema.enum && schema.enum.length > 0) {
+		return faker.helpers.arrayElement(schema.enum);
+	}
+
+	// Handle examples
+	if (schema.example !== undefined) {
+		return schema.example;
+	}
+
+	// Handle default values
+	if (schema.default !== undefined) {
+		return schema.default;
+	}
+
+	switch (type) {
+		case "string":
+			return generateStringValue(format, schema);
+
+		case "integer":
+			return generateIntegerValue(schema);
+
+		case "number":
+			return generateNumberValue(schema);
+
+		case "boolean":
+			return faker.datatype.boolean();
+
+		case "null":
+			return null;
+
+		default:
+			return faker.lorem.word();
+	}
+}
+
+/**
+ * Generate a string value based on format
+ * @param {string} format - String format
+ * @param {object} schema - Schema with constraints
+ * @returns {string} Generated string
+ */
+function generateStringValue(format, schema) {
+	switch (format) {
+		case "email":
+			return faker.internet.email();
+
+		case "uuid":
+			return faker.string.uuid();
+
+		case "uri":
+		case "url":
+			return faker.internet.url();
+
+		case "hostname":
+			return faker.internet.domainName();
+
+		case "ipv4":
+			return faker.internet.ipv4();
+
+		case "ipv6":
+			return faker.internet.ipv6();
+
+		case "date":
+			return faker.date.recent().toISOString().split("T")[0];
+
+		case "date-time":
+			return faker.date.recent().toISOString();
+
+		case "time":
+			return faker.date.recent().toISOString().split("T")[1].split(".")[0];
+
+		case "password":
+			return faker.internet.password();
+
+		case "byte":
+			return Buffer.from(faker.lorem.word()).toString("base64");
+
+		case "binary":
+			return faker.string.alphanumeric(32);
+
+		case "phone":
+			return faker.phone.number();
+
+		case "color":
+			return faker.color.rgb();
+
+		default:
+			// Use property name hints if available
+			return generateStringByPattern(schema);
+	}
+}
+
+/**
+ * Generate string based on property name patterns
+ * @param {object} schema - Schema with property name
+ * @returns {string} Generated string
+ */
+function generateStringByPattern(schema) {
+	const name = (schema.propertyName || "").toLowerCase();
+
+	// Common field name patterns
+	if (name.includes("name")) {
+		if (name.includes("first")) return faker.person.firstName();
+		if (name.includes("last")) return faker.person.lastName();
+		if (name.includes("full")) return faker.person.fullName();
+		if (name.includes("company")) return faker.company.name();
+		return faker.person.fullName();
+	}
+
+	if (name.includes("email")) return faker.internet.email();
+	if (name.includes("phone") || name.includes("mobile"))
+		return faker.phone.number();
+	if (name.includes("address")) return faker.location.streetAddress();
+	if (name.includes("city")) return faker.location.city();
+	if (name.includes("state")) return faker.location.state();
+	if (name.includes("country")) return faker.location.country();
+	if (name.includes("zip") || name.includes("postal"))
+		return faker.location.zipCode();
+	if (name.includes("url") || name.includes("link")) return faker.internet.url();
+	if (name.includes("image") || name.includes("avatar") || name.includes("photo"))
+		return faker.image.url();
+	if (name.includes("description") || name.includes("bio"))
+		return faker.lorem.paragraph();
+	if (name.includes("title")) return faker.lorem.sentence();
+	if (name.includes("slug")) return faker.helpers.slugify(faker.lorem.words(3));
+	if (name.includes("color")) return faker.color.rgb();
+	if (name.includes("token") || name.includes("key"))
+		return faker.string.alphanumeric(32);
+
+	// Apply length constraints
+	const minLength = schema.minLength || 1;
+	const maxLength = schema.maxLength || 50;
+	const length = faker.number.int({ min: minLength, max: maxLength });
+
+	if (schema.pattern) {
+		// Can't easily generate from regex, return simple string
+		return faker.string.alphanumeric(length);
+	}
+
+	return faker.lorem.words(Math.ceil(length / 6));
+}
+
+/**
+ * Generate an integer value with constraints
+ * @param {object} schema - Schema with constraints
+ * @returns {number} Generated integer
+ */
+function generateIntegerValue(schema) {
+	const min = schema.minimum ?? 0;
+	const max = schema.maximum ?? 10000;
+	const exclusiveMin = schema.exclusiveMinimum ? 1 : 0;
+	const exclusiveMax = schema.exclusiveMaximum ? 1 : 0;
+
+	return faker.number.int({
+		min: min + exclusiveMin,
+		max: max - exclusiveMax,
+	});
+}
+
+/**
+ * Generate a number value with constraints
+ * @param {object} schema - Schema with constraints
+ * @returns {number} Generated number
+ */
+function generateNumberValue(schema) {
+	const min = schema.minimum ?? 0;
+	const max = schema.maximum ?? 10000;
+
+	return faker.number.float({
+		min,
+		max,
+		fractionDigits: 2,
+	});
+}
+
+/**
+ * Generate data from a JSON Schema
+ * @param {object} schema - JSON Schema definition
+ * @param {object} spec - Full OpenAPI spec for $ref resolution
+ * @param {string} propertyName - Name of the property (for hints)
+ * @param {number} depth - Current recursion depth
+ * @returns {*} Generated data
+ */
+function generateFromSchema(schema, spec = {}, propertyName = "", depth = 0) {
+	// Prevent infinite recursion
+	if (depth > 10) {
+		return null;
+	}
+
+	// Handle null/undefined schema
+	if (!schema) {
+		return null;
+	}
+
+	// Handle $ref
+	if (schema.$ref) {
+		const resolved = resolveRef(schema.$ref, spec);
+		if (resolved) {
+			return generateFromSchema(resolved, spec, propertyName, depth + 1);
+		}
+		return null;
+	}
+
+	// Handle allOf (merge schemas)
+	if (schema.allOf) {
+		const merged = {};
+		for (const subSchema of schema.allOf) {
+			const generated = generateFromSchema(subSchema, spec, propertyName, depth + 1);
+			if (generated && typeof generated === "object") {
+				Object.assign(merged, generated);
+			}
+		}
+		return merged;
+	}
+
+	// Handle oneOf/anyOf (pick first)
+	if (schema.oneOf && schema.oneOf.length > 0) {
+		return generateFromSchema(schema.oneOf[0], spec, propertyName, depth + 1);
+	}
+	if (schema.anyOf && schema.anyOf.length > 0) {
+		return generateFromSchema(schema.anyOf[0], spec, propertyName, depth + 1);
+	}
+
+	// Add property name hint to schema for string generation
+	const schemaWithHint = { ...schema, propertyName };
+
+	// Handle by type
+	const type = schema.type || "object";
+
+	if (type === "object" || schema.properties) {
+		return generateObject(schema, spec, depth);
+	}
+
+	if (type === "array") {
+		return generateArray(schema, spec, depth);
+	}
+
+	// Primitive types
+	return generateValue(type, schema.format, schemaWithHint);
+}
+
+/**
+ * Generate an object from schema
+ * @param {object} schema - Object schema
+ * @param {object} spec - Full spec for refs
+ * @param {number} depth - Recursion depth
+ * @returns {object} Generated object
+ */
+function generateObject(schema, spec, depth) {
+	const result = {};
+
+	if (schema.properties) {
+		for (const [key, propSchema] of Object.entries(schema.properties)) {
+			result[key] = generateFromSchema(propSchema, spec, key, depth + 1);
+		}
+	}
+
+	// Handle additionalProperties if no properties defined
+	if (!schema.properties && schema.additionalProperties) {
+		const count = faker.number.int({ min: 1, max: 3 });
+		for (let i = 0; i < count; i++) {
+			const key = faker.lorem.word();
+			result[key] = generateFromSchema(
+				schema.additionalProperties === true ? { type: "string" } : schema.additionalProperties,
+				spec,
+				key,
+				depth + 1
+			);
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Generate an array from schema
+ * @param {object} schema - Array schema
+ * @param {object} spec - Full spec for refs
+ * @param {number} depth - Recursion depth
+ * @returns {array} Generated array
+ */
+function generateArray(schema, spec, depth) {
+	const minItems = schema.minItems ?? 1;
+	const maxItems = schema.maxItems ?? 5;
+	const count = faker.number.int({ min: minItems, max: maxItems });
+
+	const items = [];
+	const itemSchema = schema.items || { type: "string" };
+
+	for (let i = 0; i < count; i++) {
+		items.push(generateFromSchema(itemSchema, spec, "", depth + 1));
+	}
+
+	return items;
+}
+
+/**
+ * Generate a response body from an OpenAPI response schema
+ * @param {object} responseSchema - Response schema from OpenAPI
+ * @param {object} spec - Full OpenAPI spec
+ * @returns {*} Generated response body
+ */
+function generateResponse(responseSchema, spec) {
+	if (!responseSchema) {
+		return {};
+	}
+
+	// Handle content type (prefer JSON)
+	const content = responseSchema.content;
+	if (content) {
+		const jsonContent =
+			content["application/json"] ||
+			content["application/vnd.api+json"] ||
+			content["*/*"];
+
+		if (jsonContent && jsonContent.schema) {
+			return generateFromSchema(jsonContent.schema, spec);
+		}
+	}
+
+	// Direct schema (OpenAPI 2.0 style)
+	if (responseSchema.schema) {
+		return generateFromSchema(responseSchema.schema, spec);
+	}
+
+	return {};
+}
+
+/**
+ * Generate an error response
+ * @param {number} status - HTTP status code
+ * @param {string} message - Error message
+ * @returns {object} Error response object
+ */
+function generateErrorResponse(status, message) {
+	return {
+		error: true,
+		status,
+		message,
+		timestamp: new Date().toISOString(),
+	};
+}
+
+module.exports = {
+	generateFromSchema,
+	generateResponse,
+	generateValue,
+	generateErrorResponse,
+	resolveRef,
+};

package/runtime/mock-api/route-generator.js

@@ -0,0 +1,323 @@
+/**
+ * Route Generator
+ *
+ * Generates Express routes from OpenAPI path definitions.
+ * Supports x-mock extensions for delays, error simulation, and scenarios.
+ */
+
+const express = require("express");
+const { generateResponse, generateErrorResponse } = require("./response-generator");
+const { createAuthMiddleware } = require("./auth-middleware");
+
+// HTTP methods supported by Express
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head"];
+
+/**
+ * Convert OpenAPI path to Express path
+ * e.g., /events/{eventId}/checkin -> /events/:eventId/checkin
+ * @param {string} openApiPath - OpenAPI path with {param} syntax
+ * @returns {string} Express path with :param syntax
+ */
+function convertPath(openApiPath) {
+	return openApiPath.replace(/\{([^}]+)\}/g, ":$1");
+}
+
+/**
+ * Get response schema for a given status code
+ * @param {object} operation - OpenAPI operation object
+ * @param {number} status - HTTP status code
+ * @returns {object|null} Response schema
+ */
+function getResponseSchema(operation, status) {
+	if (!operation.responses) {
+		return null;
+	}
+
+	// Try exact status code
+	if (operation.responses[status]) {
+		return operation.responses[status];
+	}
+
+	// Try wildcard (2XX, 4XX, etc.)
+	const wildcard = `${Math.floor(status / 100)}XX`;
+	if (operation.responses[wildcard]) {
+		return operation.responses[wildcard];
+	}
+
+	// Try default
+	if (operation.responses.default) {
+		return operation.responses.default;
+	}
+
+	return null;
+}
+
+/**
+ * Get the default success status code for an operation
+ * @param {string} method - HTTP method
+ * @param {object} operation - OpenAPI operation
+ * @returns {number} Status code
+ */
+function getSuccessStatus(method, operation) {
+	const responses = operation.responses || {};
+
+	// Check for explicit success codes
+	for (const code of ["200", "201", "202", "204"]) {
+		if (responses[code]) {
+			return parseInt(code);
+		}
+	}
+
+	// Default by method
+	if (method === "post") return 201;
+	if (method === "delete") return 204;
+	return 200;
+}
+
+/**
+ * Apply delay if configured
+ * @param {object} mockConfig - x-mock configuration
+ * @returns {Promise} Resolves after delay
+ */
+function applyDelay(mockConfig) {
+	const delay = mockConfig.delay || parseInt(process.env.MOCK_API_DELAY) || 0;
+
+	if (delay > 0) {
+		return new Promise((resolve) => setTimeout(resolve, delay));
+	}
+
+	return Promise.resolve();
+}
+
+/**
+ * Determine if this request should simulate an error
+ * @param {object} mockConfig - x-mock configuration
+ * @returns {boolean} True if should error
+ */
+function shouldSimulateError(mockConfig) {
+	const errorRate = mockConfig.errorRate || 0;
+
+	if (errorRate <= 0) return false;
+	if (errorRate >= 1) return true;
+
+	return Math.random() < errorRate;
+}
+
+/**
+ * Select a scenario based on weights
+ * @param {object} scenarios - Scenario definitions
+ * @returns {object|null} Selected scenario or null
+ */
+function selectScenario(scenarios) {
+	if (!scenarios || typeof scenarios !== "object") {
+		return null;
+	}
+
+	const entries = Object.entries(scenarios);
+	if (entries.length === 0) return null;
+
+	// Calculate total weight
+	const totalWeight = entries.reduce(
+		(sum, [, config]) => sum + (config.weight || 1),
+		0
+	);
+
+	// Random selection
+	let random = Math.random() * totalWeight;
+
+	for (const [name, config] of entries) {
+		const weight = config.weight || 1;
+		random -= weight;
+
+		if (random <= 0) {
+			return { name, ...config };
+		}
+	}
+
+	// Fallback to first scenario
+	const [name, config] = entries[0];
+	return { name, ...config };
+}
+
+/**
+ * Build a route handler for an OpenAPI operation
+ * @param {string} method - HTTP method
+ * @param {string} path - Original OpenAPI path
+ * @param {object} operation - OpenAPI operation object
+ * @param {object} spec - Full OpenAPI spec
+ * @param {object} options - Additional options (io for socket triggers)
+ * @returns {function} Express route handler
+ */
+function buildRouteHandler(method, path, operation, spec, options = {}) {
+	const { io, socketTriggers } = options;
+
+	return async (req, res) => {
+		const mockConfig = operation["x-mock"] || {};
+		const operationId = operation.operationId || `${method.toUpperCase()} ${path}`;
+
+		console.log(`🎭 Mock API: ${operationId}`);
+
+		try {
+			// Apply delay
+			await applyDelay(mockConfig);
+
+			// Check for scenario mode
+			const scenario = selectScenario(mockConfig.scenarios);
+
+			// Determine if we should simulate an error
+			if (shouldSimulateError(mockConfig)) {
+				const errorSchema = getResponseSchema(operation, 500);
+				const errorBody = errorSchema
+					? generateResponse(errorSchema, spec)
+					: generateErrorResponse(500, "Simulated server error");
+
+				console.log(`   ⚠️  Simulated error (errorRate: ${mockConfig.errorRate})`);
+				return res.status(500).json(errorBody);
+			}
+
+			// Use scenario status if defined
+			const status = scenario?.status || getSuccessStatus(method, operation);
+
+			// Get response schema for this status
+			const responseSchema = getResponseSchema(operation, status);
+
+			// Generate response body
+			let body;
+			if (status === 204) {
+				// No content
+				body = undefined;
+			} else if (scenario?.response) {
+				// Use scenario-defined response
+				body = scenario.response;
+			} else if (responseSchema) {
+				body = generateResponse(responseSchema, spec);
+			} else {
+				body = { success: true };
+			}
+
+			// Log response info
+			if (scenario) {
+				console.log(`   📋 Scenario: ${scenario.name}`);
+			}
+			console.log(`   ✅ Status: ${status}`);
+
+			// Send response
+			if (status === 204) {
+				res.status(204).end();
+			} else {
+				res.status(status).json(body);
+			}
+
+			// Trigger socket events if configured
+			if (io && socketTriggers) {
+				const { triggerSocketEvents } = require("./socket-triggers");
+				const operationKey = `${method.toUpperCase()} ${path}`;
+
+				triggerSocketEvents(io, socketTriggers, operationKey, {
+					request: {
+						method: req.method,
+						path: req.path,
+						params: req.params,
+						query: req.query,
+						body: req.body,
+					},
+					response: {
+						status,
+						body,
+					},
+				});
+			}
+		} catch (error) {
+			console.error(`   ❌ Error: ${error.message}`);
+			res.status(500).json(generateErrorResponse(500, error.message));
+		}
+	};
+}
+
+/**
+ * Generate Express routes from OpenAPI spec
+ * @param {object} openApiSpec - OpenAPI specification
+ * @param {object} options - Options (io for socket, socketTriggers map)
+ * @returns {express.Router} Express router with mock routes
+ */
+function generateRoutes(openApiSpec, options = {}) {
+	const router = express.Router();
+
+	if (!openApiSpec || !openApiSpec.paths) {
+		console.warn("⚠️  No paths found in OpenAPI spec");
+		return router;
+	}
+
+	let routeCount = 0;
+
+	// Iterate over all paths
+	for (const [path, pathItem] of Object.entries(openApiSpec.paths)) {
+		const expressPath = convertPath(path);
+
+		// Iterate over HTTP methods
+		for (const method of HTTP_METHODS) {
+			const operation = pathItem[method];
+
+			if (!operation) continue;
+
+			// Create auth middleware for this operation
+			const authMiddleware = createAuthMiddleware(operation);
+
+			// Create route handler
+			const handler = buildRouteHandler(method, path, operation, openApiSpec, options);
+
+			// Register route
+			router[method](expressPath, authMiddleware, handler);
+			routeCount++;
+
+			const operationId = operation.operationId || `${method.toUpperCase()} ${path}`;
+			console.log(`   📍 ${method.toUpperCase()} ${expressPath} (${operationId})`);
+		}
+	}
+
+	console.log(`✅ Generated ${routeCount} mock routes`);
+
+	return router;
+}
+
+/**
+ * Get route statistics from OpenAPI spec
+ * @param {object} openApiSpec - OpenAPI specification
+ * @returns {object} Statistics object
+ */
+function getRouteStats(openApiSpec) {
+	if (!openApiSpec || !openApiSpec.paths) {
+		return { total: 0, byMethod: {} };
+	}
+
+	const stats = {
+		total: 0,
+		byMethod: {},
+		paths: [],
+	};
+
+	for (const [path, pathItem] of Object.entries(openApiSpec.paths)) {
+		for (const method of HTTP_METHODS) {
+			if (pathItem[method]) {
+				stats.total++;
+				stats.byMethod[method] = (stats.byMethod[method] || 0) + 1;
+				stats.paths.push({
+					method: method.toUpperCase(),
+					path,
+					operationId: pathItem[method].operationId,
+				});
+			}
+		}
+	}
+
+	return stats;
+}
+
+module.exports = {
+	generateRoutes,
+	convertPath,
+	getResponseSchema,
+	getSuccessStatus,
+	buildRouteHandler,
+	getRouteStats,
+};