mockforge_openapi/
route.rs

1//! OpenAPI route generation from specifications
2//!
3//! This module provides functionality for generating Axum routes
4//! from OpenAPI path definitions.
5
6use crate::response_selection::{ResponseSelectionMode, ResponseSelector};
7use crate::spec::OpenApiSpec;
8use mockforge_foundation::ai_response::AiResponseConfig;
9use mockforge_foundation::error::Result;
10use mockforge_foundation::intelligent_behavior::Persona;
11use openapiv3::{Operation, PathItem, ReferenceOr};
12use std::collections::BTreeMap;
13use std::sync::Arc;
14
15/// Extract path parameters from an OpenAPI path template
16fn extract_path_parameters(path_template: &str) -> Vec<String> {
17    let mut params = Vec::new();
18    let mut in_param = false;
19    let mut current_param = String::new();
20
21    for ch in path_template.chars() {
22        match ch {
23            '{' => {
24                in_param = true;
25                current_param.clear();
26            }
27            '}' => {
28                if in_param {
29                    params.push(current_param.clone());
30                    in_param = false;
31                }
32            }
33            ch if in_param => {
34                current_param.push(ch);
35            }
36            _ => {}
37        }
38    }
39
40    params
41}
42
43/// OpenAPI route wrapper with additional metadata
44#[derive(Debug, Clone)]
45pub struct OpenApiRoute {
46    /// The HTTP method
47    pub method: String,
48    /// The path pattern
49    pub path: String,
50    /// The OpenAPI operation
51    pub operation: Operation,
52    /// Route-specific metadata
53    pub metadata: BTreeMap<String, String>,
54    /// Path parameters extracted from the path
55    pub parameters: Vec<String>,
56    /// Reference to the OpenAPI spec for response generation
57    pub spec: Arc<OpenApiSpec>,
58    /// AI response configuration (parsed from x-mockforge-ai extension)
59    pub ai_config: Option<AiResponseConfig>,
60    /// Response selection mode (parsed from x-mockforge-response-selection extension)
61    pub response_selection_mode: ResponseSelectionMode,
62    /// Response selector for sequential/random modes (shared across requests)
63    pub response_selector: Arc<ResponseSelector>,
64    /// Active persona for consistent data generation (optional)
65    pub persona: Option<Arc<Persona>>,
66}
67
68impl OpenApiRoute {
69    /// Create a new OpenApiRoute
70    pub fn new(method: String, path: String, operation: Operation, spec: Arc<OpenApiSpec>) -> Self {
71        Self::new_with_persona(method, path, operation, spec, None)
72    }
73
74    /// Create a new OpenApiRoute with persona
75    pub fn new_with_persona(
76        method: String,
77        path: String,
78        operation: Operation,
79        spec: Arc<OpenApiSpec>,
80        persona: Option<Arc<Persona>>,
81    ) -> Self {
82        let parameters = extract_path_parameters(&path);
83
84        // Parse AI configuration from x-mockforge-ai vendor extension
85        let ai_config = Self::parse_ai_config(&operation);
86
87        // Parse response selection mode from x-mockforge-response-selection extension
88        let response_selection_mode = Self::parse_response_selection_mode(&operation);
89        let response_selector = Arc::new(ResponseSelector::new(response_selection_mode));
90
91        Self {
92            method,
93            path,
94            operation,
95            metadata: BTreeMap::new(),
96            parameters,
97            spec,
98            ai_config,
99            response_selection_mode,
100            response_selector,
101            persona,
102        }
103    }
104
105    /// Parse AI configuration from OpenAPI operation's vendor extensions
106    fn parse_ai_config(operation: &Operation) -> Option<AiResponseConfig> {
107        // Check for x-mockforge-ai extension
108        if let Some(ai_config_value) = operation.extensions.get("x-mockforge-ai") {
109            // Try to deserialize the AI config from the extension value
110            match serde_json::from_value::<AiResponseConfig>(ai_config_value.clone()) {
111                Ok(config) => {
112                    if config.is_active() {
113                        tracing::debug!(
114                            "Parsed AI config for operation {}: mode={:?}, prompt={:?}",
115                            operation.operation_id.as_deref().unwrap_or("unknown"),
116                            config.mode,
117                            config.prompt
118                        );
119                        return Some(config);
120                    }
121                }
122                Err(e) => {
123                    tracing::warn!(
124                        "Failed to parse x-mockforge-ai extension for operation {}: {}",
125                        operation.operation_id.as_deref().unwrap_or("unknown"),
126                        e
127                    );
128                }
129            }
130        }
131        None
132    }
133
134    /// Parse response selection mode from OpenAPI operation's vendor extensions
135    fn parse_response_selection_mode(operation: &Operation) -> ResponseSelectionMode {
136        // Check for environment variable override (per-operation or global)
137        let op_id = operation.operation_id.as_deref().unwrap_or("unknown");
138
139        // Try operation-specific env var first: MOCKFORGE_RESPONSE_SELECTION_<OPERATION_ID>
140        if let Ok(op_env_var) = std::env::var(format!(
141            "MOCKFORGE_RESPONSE_SELECTION_{}",
142            op_id.to_uppercase().replace('-', "_")
143        )) {
144            if let Some(mode) = ResponseSelectionMode::from_str(&op_env_var) {
145                tracing::debug!(
146                    "Using response selection mode from env var for operation {}: {:?}",
147                    op_id,
148                    mode
149                );
150                return mode;
151            }
152        }
153
154        // Check global env var: MOCKFORGE_RESPONSE_SELECTION_MODE
155        if let Ok(global_mode_str) = std::env::var("MOCKFORGE_RESPONSE_SELECTION_MODE") {
156            if let Some(mode) = ResponseSelectionMode::from_str(&global_mode_str) {
157                tracing::debug!("Using global response selection mode from env var: {:?}", mode);
158                return mode;
159            }
160        }
161
162        // Check for x-mockforge-response-selection extension
163        if let Some(selection_value) = operation.extensions.get("x-mockforge-response-selection") {
164            // Try to parse as string first
165            if let Some(mode_str) = selection_value.as_str() {
166                if let Some(mode) = ResponseSelectionMode::from_str(mode_str) {
167                    tracing::debug!(
168                        "Parsed response selection mode for operation {}: {:?}",
169                        op_id,
170                        mode
171                    );
172                    return mode;
173                }
174            }
175            // Try to parse as object with mode field
176            if let Some(obj) = selection_value.as_object() {
177                if let Some(mode_str) = obj.get("mode").and_then(|v| v.as_str()) {
178                    if let Some(mode) = ResponseSelectionMode::from_str(mode_str) {
179                        tracing::debug!(
180                            "Parsed response selection mode for operation {}: {:?}",
181                            op_id,
182                            mode
183                        );
184                        return mode;
185                    }
186                }
187            }
188            tracing::warn!(
189                "Failed to parse x-mockforge-response-selection extension for operation {}",
190                op_id
191            );
192        }
193        // Default to First mode
194        ResponseSelectionMode::First
195    }
196
197    /// Create an OpenApiRoute from an operation
198    pub fn from_operation(
199        method: &str,
200        path: String,
201        operation: &Operation,
202        spec: Arc<OpenApiSpec>,
203    ) -> Self {
204        Self::from_operation_with_persona(method, path, operation, spec, None)
205    }
206
207    /// Create a new OpenApiRoute from an operation with optional persona
208    pub fn from_operation_with_persona(
209        method: &str,
210        path: String,
211        operation: &Operation,
212        spec: Arc<OpenApiSpec>,
213        persona: Option<Arc<Persona>>,
214    ) -> Self {
215        Self::new_with_persona(method.to_string(), path, operation.clone(), spec, persona)
216    }
217
218    /// Convert OpenAPI path to Axum-compatible path format
219    pub fn axum_path(&self) -> String {
220        // Strip query string if present (some non-standard OpenAPI specs embed query params in path)
221        // Axum v0.7+ uses {param} format, same as OpenAPI
222        let path = self.path.split('?').next().unwrap_or(&self.path);
223
224        // Handle empty function call parens: functionName() → functionName
225        if path.contains("()") {
226            let path = path.replace("()", "");
227            return path;
228        }
229
230        // Handle OData function call syntax: functionName(key='{param}',key2={param2})
231        // Also handles Microsoft Graph style: functionName(key='{param}') where quotes wrap braces
232        // Convert to: functionName/{param}/{param2}
233        // This prevents Axum from panicking on multiple params per segment or invalid chars
234        if path.contains('(') && path.contains('=') {
235            let mut result = String::with_capacity(path.len());
236            let mut chars = path.chars().peekable();
237
238            while let Some(ch) = chars.next() {
239                if ch == '(' {
240                    // Extract params from inside parentheses
241                    let mut paren_content = String::new();
242                    for c in chars.by_ref() {
243                        if c == ')' {
244                            break;
245                        }
246                        paren_content.push(c);
247                    }
248                    // Parse key='{value}' or key={value} pairs
249                    for part in paren_content.split(',') {
250                        if let Some((_key, value)) = part.split_once('=') {
251                            let param = value.trim_matches(|c| c == '\'' || c == '"');
252                            result.push('/');
253                            result.push_str(param);
254                        }
255                    }
256                } else {
257                    result.push(ch);
258                }
259            }
260            return result;
261        }
262
263        path.to_string()
264    }
265
266    /// Returns true if this route's path can be registered with Axum's router.
267    ///
268    /// Paths that contain characters Axum can't handle (e.g., unmatched braces,
269    /// multiple params per segment after conversion) are considered invalid.
270    pub fn is_valid_axum_path(&self) -> bool {
271        let path = self.axum_path();
272        // If parentheses survived conversion, the path is invalid for Axum
273        if path.contains('(') || path.contains(')') {
274            return false;
275        }
276        // Each segment may contain at most one `{param}` capture
277        for segment in path.split('/') {
278            let brace_count = segment.matches('{').count();
279            if brace_count > 1 {
280                return false;
281            }
282            // A segment with a param must be ONLY the param (e.g. `{id}` not `prefix{id}suffix`)
283            // unless it's a wildcard. Axum allows `{*rest}` as a catch-all.
284            if brace_count == 1
285                && segment
286                    != format!(
287                        "{{{}}}",
288                        segment
289                            .trim_matches(|c: char| c != '{' && c != '}')
290                            .trim_matches(|c| c == '{' || c == '}')
291                    )
292            {
293                // Segment has a param mixed with literal text — check if it's truly invalid
294                // Axum 0.8 allows `{param}` as full segment only
295                if !segment.starts_with('{') || !segment.ends_with('}') {
296                    return false;
297                }
298            }
299        }
300        true
301    }
302
303    /// Add metadata to the route
304    pub fn with_metadata(mut self, key: String, value: String) -> Self {
305        self.metadata.insert(key, value);
306        self
307    }
308
309    /// Generate a mock response with status code for this route (async version with AI support)
310    ///
311    /// This method checks if AI response generation is configured and uses it if available,
312    /// otherwise falls back to standard OpenAPI response generation.
313    ///
314    /// # Arguments
315    /// * `context` - The request context for AI prompt expansion
316    /// * `ai_generator` - Optional AI generator implementation for actual LLM calls
317    pub async fn mock_response_with_status_async(
318        &self,
319        context: &mockforge_foundation::ai_response::RequestContext,
320        ai_generator: Option<&dyn crate::response::AiGenerator>,
321    ) -> (u16, serde_json::Value) {
322        use crate::response::ResponseGenerator;
323
324        // Find the first available status code from the OpenAPI spec
325        let status_code = self.find_first_available_status_code();
326
327        // Check if AI response generation is configured
328        if let Some(ai_config) = &self.ai_config {
329            if ai_config.is_active() {
330                tracing::info!(
331                    "Using AI-assisted response generation for {} {}",
332                    self.method,
333                    self.path
334                );
335
336                match ResponseGenerator::generate_ai_response(ai_config, context, ai_generator)
337                    .await
338                {
339                    Ok(response_body) => {
340                        tracing::debug!(
341                            "AI response generated successfully for {} {}: {:?}",
342                            self.method,
343                            self.path,
344                            response_body
345                        );
346                        return (status_code, response_body);
347                    }
348                    Err(e) => {
349                        tracing::warn!(
350                            "AI response generation failed for {} {}: {}, falling back to standard generation",
351                            self.method,
352                            self.path,
353                            e
354                        );
355                        // Continue to standard generation on error
356                    }
357                }
358            }
359        }
360
361        // Standard OpenAPI-based response generation
362        let expand_tokens = std::env::var("MOCKFORGE_RESPONSE_TEMPLATE_EXPAND")
363            .map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
364            .unwrap_or(false);
365
366        // Use response selection mode for multiple examples
367        let mode = Some(self.response_selection_mode);
368        let selector = Some(self.response_selector.as_ref());
369
370        // Get persona reference for response generation
371        let persona_ref = self.persona.as_deref();
372
373        match ResponseGenerator::generate_response_with_expansion_and_mode_and_persona(
374            &self.spec,
375            &self.operation,
376            status_code,
377            Some("application/json"),
378            expand_tokens,
379            mode,
380            selector,
381            persona_ref,
382        ) {
383            Ok(response_body) => {
384                tracing::debug!(
385                    "ResponseGenerator succeeded for {} {} with status {}: {:?}",
386                    self.method,
387                    self.path,
388                    status_code,
389                    response_body
390                );
391                (status_code, response_body)
392            }
393            Err(e) => {
394                tracing::debug!(
395                    "ResponseGenerator failed for {} {}: {}, using fallback",
396                    self.method,
397                    self.path,
398                    e
399                );
400                // Fallback to simple mock response if schema-based generation fails
401                let response_body = serde_json::json!({
402                    "message": format!("Mock response for {} {}", self.method, self.path),
403                    "operation_id": self.operation.operation_id,
404                    "status": status_code
405                });
406                (status_code, response_body)
407            }
408        }
409    }
410
411    /// Generate a mock response with status code for this route (synchronous version)
412    ///
413    /// Note: This method does not support AI-assisted response generation.
414    /// Use `mock_response_with_status_async` for AI features.
415    pub fn mock_response_with_status(&self) -> (u16, serde_json::Value) {
416        self.mock_response_with_status_and_scenario(None)
417    }
418
419    /// Generate a mock response with status code and scenario selection
420    ///
421    /// # Arguments
422    /// * `scenario` - Optional scenario name to select from the OpenAPI examples
423    ///
424    /// # Example
425    ///
426    /// ```rust,ignore
427    /// // Select the "error" scenario from examples
428    /// let (status, body) = route.mock_response_with_status_and_scenario(Some("error"));
429    /// ```
430    pub fn mock_response_with_status_and_scenario(
431        &self,
432        scenario: Option<&str>,
433    ) -> (u16, serde_json::Value) {
434        self.mock_response_with_status_and_scenario_and_override(scenario, None)
435    }
436
437    /// Generate a mock response with status code, scenario, and optional status override
438    ///
439    /// # Arguments
440    /// * `scenario` - Optional scenario name to select from the OpenAPI examples
441    /// * `status_override` - Optional HTTP status code to use instead of the default
442    pub fn mock_response_with_status_and_scenario_and_override(
443        &self,
444        scenario: Option<&str>,
445        status_override: Option<u16>,
446    ) -> (u16, serde_json::Value) {
447        let (status, body, _) =
448            self.mock_response_with_status_and_scenario_and_trace(scenario, status_override);
449        (status, body)
450    }
451
452    /// Generate a mock response with status code, scenario selection, and trace collection
453    ///
454    /// Returns a tuple of (status_code, response_body, trace_data)
455    pub fn mock_response_with_status_and_scenario_and_trace(
456        &self,
457        scenario: Option<&str>,
458        status_override: Option<u16>,
459    ) -> (
460        u16,
461        serde_json::Value,
462        mockforge_foundation::response_generation_trace::ResponseGenerationTrace,
463    ) {
464        use crate::response_trace;
465        use mockforge_foundation::response_generation_trace::ResponseGenerationTrace;
466
467        // Use status override if the spec has a response for that code, otherwise default
468        let status_code = status_override
469            .filter(|code| self.has_response_for_status(*code))
470            .unwrap_or_else(|| self.find_first_available_status_code());
471
472        // Check if token expansion should be enabled
473        let expand_tokens = std::env::var("MOCKFORGE_RESPONSE_TEMPLATE_EXPAND")
474            .map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
475            .unwrap_or(false);
476
477        // Use response selection mode for multiple examples
478        let mode = Some(self.response_selection_mode);
479        let selector = Some(self.response_selector.as_ref());
480
481        // Try to generate with trace collection
482        match response_trace::generate_response_with_trace(
483            &self.spec,
484            &self.operation,
485            status_code,
486            Some("application/json"),
487            expand_tokens,
488            scenario,
489            mode,
490            selector,
491            None, // No persona in basic route
492        ) {
493            Ok((response_body, trace)) => {
494                tracing::debug!(
495                    "ResponseGenerator succeeded for {} {} with status {} and scenario {:?}: {:?}",
496                    self.method,
497                    self.path,
498                    status_code,
499                    scenario,
500                    response_body
501                );
502                (status_code, response_body, trace)
503            }
504            Err(e) => {
505                tracing::debug!(
506                    "ResponseGenerator failed for {} {}: {}, using fallback",
507                    self.method,
508                    self.path,
509                    e
510                );
511                // Fallback to simple mock response if schema-based generation fails
512                let response_body = serde_json::json!({
513                    "message": format!("Mock response for {} {}", self.method, self.path),
514                    "operation_id": self.operation.operation_id,
515                    "status": status_code
516                });
517                // Create a minimal trace for fallback
518                let mut trace = ResponseGenerationTrace::new();
519                trace.set_final_payload(response_body.clone());
520                trace.add_metadata("fallback".to_string(), serde_json::json!(true));
521                trace.add_metadata("error".to_string(), serde_json::json!(e.to_string()));
522                (status_code, response_body, trace)
523            }
524        }
525    }
526
527    /// Check if the operation declares a response for the given HTTP status code
528    pub fn has_response_for_status(&self, code: u16) -> bool {
529        self.operation
530            .responses
531            .responses
532            .iter()
533            .any(|(status, _)| matches!(status, openapiv3::StatusCode::Code(c) if *c == code))
534    }
535
536    /// Find the first available status code from the OpenAPI operation responses
537    pub fn find_first_available_status_code(&self) -> u16 {
538        // Look for the first available status code in the responses
539        for (status, _) in &self.operation.responses.responses {
540            match status {
541                openapiv3::StatusCode::Code(code) => {
542                    return *code;
543                }
544                openapiv3::StatusCode::Range(range) => {
545                    // For ranges, use the appropriate status code
546                    match range {
547                        2 => return 200, // 2XX range
548                        3 => return 300, // 3XX range
549                        4 => return 400, // 4XX range
550                        5 => return 500, // 5XX range
551                        _ => continue,   // Skip unknown ranges
552                    }
553                }
554            }
555        }
556
557        // If no specific status codes found, check for default
558        if self.operation.responses.default.is_some() {
559            return 200; // Default to 200 for default responses
560        }
561
562        // Fallback to 200 if nothing else is available
563        200
564    }
565}
566
567/// OpenAPI operation wrapper with path context
568#[derive(Debug, Clone)]
569pub struct OpenApiOperation {
570    /// The HTTP method
571    pub method: String,
572    /// The path this operation belongs to
573    pub path: String,
574    /// The OpenAPI operation
575    pub operation: Operation,
576}
577
578impl OpenApiOperation {
579    /// Create a new OpenApiOperation
580    pub fn new(method: String, path: String, operation: Operation) -> Self {
581        Self {
582            method,
583            path,
584            operation,
585        }
586    }
587}
588
589/// Route generation utilities
590pub struct RouteGenerator;
591
592impl RouteGenerator {
593    /// Generate routes from an OpenAPI path item
594    pub fn generate_routes_from_path(
595        path: &str,
596        path_item: &ReferenceOr<PathItem>,
597        spec: &Arc<OpenApiSpec>,
598    ) -> Result<Vec<OpenApiRoute>> {
599        Self::generate_routes_from_path_with_persona(path, path_item, spec, None)
600    }
601
602    /// Generate routes from an OpenAPI path item with optional persona
603    pub fn generate_routes_from_path_with_persona(
604        path: &str,
605        path_item: &ReferenceOr<PathItem>,
606        spec: &Arc<OpenApiSpec>,
607        persona: Option<Arc<Persona>>,
608    ) -> Result<Vec<OpenApiRoute>> {
609        let mut routes = Vec::new();
610
611        if let Some(item) = path_item.as_item() {
612            // Generate route for each HTTP method
613            if let Some(op) = &item.get {
614                routes.push(OpenApiRoute::new_with_persona(
615                    "GET".to_string(),
616                    path.to_string(),
617                    op.clone(),
618                    spec.clone(),
619                    persona.clone(),
620                ));
621            }
622            if let Some(op) = &item.post {
623                routes.push(OpenApiRoute::new_with_persona(
624                    "POST".to_string(),
625                    path.to_string(),
626                    op.clone(),
627                    spec.clone(),
628                    persona.clone(),
629                ));
630            }
631            if let Some(op) = &item.put {
632                routes.push(OpenApiRoute::new_with_persona(
633                    "PUT".to_string(),
634                    path.to_string(),
635                    op.clone(),
636                    spec.clone(),
637                    persona.clone(),
638                ));
639            }
640            if let Some(op) = &item.delete {
641                routes.push(OpenApiRoute::new_with_persona(
642                    "DELETE".to_string(),
643                    path.to_string(),
644                    op.clone(),
645                    spec.clone(),
646                    persona.clone(),
647                ));
648            }
649            if let Some(op) = &item.patch {
650                routes.push(OpenApiRoute::new_with_persona(
651                    "PATCH".to_string(),
652                    path.to_string(),
653                    op.clone(),
654                    spec.clone(),
655                    persona.clone(),
656                ));
657            }
658            if let Some(op) = &item.head {
659                routes.push(OpenApiRoute::new_with_persona(
660                    "HEAD".to_string(),
661                    path.to_string(),
662                    op.clone(),
663                    spec.clone(),
664                    persona.clone(),
665                ));
666            }
667            if let Some(op) = &item.options {
668                routes.push(OpenApiRoute::new_with_persona(
669                    "OPTIONS".to_string(),
670                    path.to_string(),
671                    op.clone(),
672                    spec.clone(),
673                    persona.clone(),
674                ));
675            }
676            if let Some(op) = &item.trace {
677                routes.push(OpenApiRoute::new_with_persona(
678                    "TRACE".to_string(),
679                    path.to_string(),
680                    op.clone(),
681                    spec.clone(),
682                    persona.clone(),
683                ));
684            }
685        }
686
687        Ok(routes)
688    }
689}
mockforge_openapi/route.rs

mockforge_openapi/
route.rs
