mockforge_core/
lib.rs

1//! # MockForge Core
2//!
3//! Core functionality and shared logic for the MockForge mocking framework.
4//!
5//! This crate provides the foundational building blocks used across all MockForge protocols
6//! (HTTP, WebSocket, gRPC, GraphQL). It can be used as a library to programmatically create
7//! and manage mock servers, or to build custom mocking solutions.
8//!
9//! ## Overview
10//!
11//! MockForge Core includes:
12//!
13//! - **Routing & Validation**: OpenAPI-based route registration and request validation
14//! - **Request/Response Processing**: Template expansion, data generation, and transformation
15//! - **Chaos Engineering**: Latency injection, failure simulation, and traffic shaping
16//! - **Proxy & Hybrid Mode**: Forward requests to real backends with intelligent fallback
17//! - **Request Chaining**: Multi-step request workflows with context passing
18//! - **Workspace Management**: Organize and persist mock configurations
19//! - **Observability**: Request logging, metrics collection, and tracing
20//!
21//! ## Quick Start: Embedding MockForge
22//!
23//! ### Creating a Simple HTTP Mock Server
24//!
25//! ```rust,no_run
26//! use mockforge_core::{
27//!     Config, LatencyProfile, OpenApiRouteRegistry, OpenApiSpec, Result, ValidationOptions,
28//! };
29//!
30//! #[tokio::main]
31//! async fn main() -> Result<()> {
32//!     // Load OpenAPI specification
33//!     let spec = OpenApiSpec::from_file("api.json").await?;
34//!
35//!     // Create route registry with validation
36//!     let registry = OpenApiRouteRegistry::new_with_options(spec, ValidationOptions::default());
37//!
38//!     // Configure core features
39//!     let config = Config {
40//!         latency_enabled: true,
41//!         failures_enabled: false,
42//!         default_latency: LatencyProfile::with_normal_distribution(400, 120.0),
43//!         ..Default::default()
44//!     };
45//!
46//!     // Build your HTTP server with the registry
47//!     // (See mockforge-http crate for router building)
48//!
49//!     Ok(())
50//! }
51//! ```
52//!
53//! ### Request Chaining
54//!
55//! Chain multiple requests together with shared context:
56//!
57//! ```rust,no_run
58//! use mockforge_core::{
59//!     ChainConfig, ChainDefinition, ChainLink, ChainRequest, RequestChainRegistry, Result,
60//! };
61//! use mockforge_core::request_chaining::RequestBody;
62//! use serde_json::json;
63//! use std::collections::HashMap;
64//!
65//! # async fn example() -> Result<()> {
66//! let registry = RequestChainRegistry::new(ChainConfig::default());
67//!
68//! // Define a chain: create user → add to group → verify membership
69//! let chain = ChainDefinition {
70//!     id: "user_onboarding".to_string(),
71//!     name: "User Onboarding".to_string(),
72//!     description: Some("Create user → add to group".to_string()),
73//!     config: ChainConfig {
74//!         enabled: true,
75//!         ..ChainConfig::default()
76//!     },
77//!     links: vec![
78//!         ChainLink {
79//!             request: ChainRequest {
80//!                 id: "create_user".to_string(),
81//!                 method: "POST".to_string(),
82//!                 url: "https://api.example.com/users".to_string(),
83//!                 headers: HashMap::new(),
84//!                 body: Some(RequestBody::json(json!({"name": "{{faker.name}}"}))),
85//!                 depends_on: Vec::new(),
86//!                 timeout_secs: None,
87//!                 expected_status: None,
88//!                 scripting: None,
89//!             },
90//!             extract: HashMap::from([("user_id".to_string(), "create_user.body.id".to_string())]),
91//!             store_as: Some("create_user_response".to_string()),
92//!         },
93//!         ChainLink {
94//!             request: ChainRequest {
95//!                 id: "add_to_group".to_string(),
96//!                 method: "POST".to_string(),
97//!                 url: "https://api.example.com/groups/{{user_id}}/members".to_string(),
98//!                 headers: HashMap::new(),
99//!                 body: None,
100//!                 depends_on: vec!["create_user".to_string()],
101//!                 timeout_secs: None,
102//!                 expected_status: None,
103//!                 scripting: None,
104//!             },
105//!             extract: HashMap::new(),
106//!             store_as: None,
107//!         },
108//!     ],
109//!     variables: HashMap::new(),
110//!     tags: vec!["onboarding".to_string()],
111//! };
112//!
113//! registry.store().register_chain(chain).await?;
114//! # Ok(())
115//! # }
116//! ```
117//!
118//! ### Latency & Failure Injection
119//!
120//! Simulate realistic network conditions and errors:
121//!
122//! ```rust,no_run
123//! use mockforge_core::{LatencyProfile, FailureConfig, create_failure_injector};
124//!
125//! // Configure latency simulation
126//! let latency = LatencyProfile::with_normal_distribution(400, 120.0)
127//!     .with_min_ms(100)
128//!     .with_max_ms(800);
129//!
130//! // Configure failure injection
131//! let failure_config = FailureConfig {
132//!     global_error_rate: 0.05, // 5% of requests fail
133//!     default_status_codes: vec![500, 502, 503],
134//!     ..Default::default()
135//! };
136//!
137//! let injector = create_failure_injector(true, Some(failure_config));
138//! ```
139//!
140//! ## Key Modules
141//!
142//! ### OpenAPI Support
143//! - [`openapi`]: Parse and work with OpenAPI specifications
144//! - [`openapi_routes`]: Register routes from OpenAPI specs with validation
145//! - [`validation`]: Request/response validation against schemas
146//!
147//! ### Request Processing
148//! - [`routing`]: Route matching and registration
149//! - [`templating`]: Template variable expansion ({{uuid}}, {{now}}, etc.)
150//! - [`request_chaining`]: Multi-step request workflows
151//! - [`overrides`]: Dynamic request/response modifications
152//!
153//! ### Chaos Engineering
154//! - [`latency`]: Latency injection with configurable profiles
155//! - [`failure_injection`]: Simulate service failures and errors
156//! - [`traffic_shaping`]: Bandwidth limiting and packet loss
157//!
158//! ### Proxy & Hybrid
159//! - [`proxy`]: Forward requests to upstream services
160//! - [`ws_proxy`]: WebSocket proxy with message transformation
161//!
162//! ### Persistence & Import
163//! - [`workspace`]: Workspace management for organizing mocks
164//! - [`workspace_import`]: Import from Postman, Insomnia, cURL, HAR
165//! - [`record_replay`]: Record real requests and replay as fixtures
166//!
167//! ### Observability
168//! - [`request_logger`]: Centralized request logging
169//! - [`performance`]: Performance metrics and profiling
170//!
171//! ## Feature Flags
172//!
173//! This crate supports several optional features:
174//!
175//! - `openapi`: OpenAPI specification support (enabled by default)
176//! - `validation`: Request/response validation (enabled by default)
177//! - `templating`: Template expansion (enabled by default)
178//! - `chaos`: Chaos engineering features (enabled by default)
179//! - `proxy`: Proxy and hybrid mode (enabled by default)
180//! - `workspace`: Workspace management (enabled by default)
181//!
182//! ## Examples
183//!
184//! See the [examples directory](https://github.com/SaaSy-Solutions/mockforge/tree/main/examples)
185//! for complete working examples.
186//!
187//! ## Related Crates
188//!
189//! - [`mockforge-http`](https://docs.rs/mockforge-http): HTTP/REST mock server
190//! - [`mockforge-grpc`](https://docs.rs/mockforge-grpc): gRPC mock server
191//! - [`mockforge-ws`](https://docs.rs/mockforge-ws): WebSocket mock server
192//! - [`mockforge-graphql`](https://docs.rs/mockforge-graphql): GraphQL mock server
193//! - [`mockforge-plugin-core`](https://docs.rs/mockforge-plugin-core): Plugin development
194//! - [`mockforge-data`](https://docs.rs/mockforge-data): Synthetic data generation
195//!
196//! ## Documentation
197//!
198//! - [MockForge Book](https://docs.mockforge.dev/)
199//! - [API Reference](https://docs.rs/mockforge-core)
200//! - [GitHub Repository](https://github.com/SaaSy-Solutions/mockforge)
201
202#![allow(deprecated)]
203
204pub mod ab_testing;
205pub mod ai_contract_diff;
206pub mod ai_response;
207/// AI Studio - Unified AI Copilot for all AI-powered features
208pub mod ai_studio;
209/// Behavioral cloning of backends - learn from recorded traffic to create realistic mock behavior
210pub mod behavioral_cloning;
211pub mod cache;
212pub mod chain_execution;
213pub mod chaos_utilities;
214pub mod codegen;
215/// Collection export utilities for exporting mock data in various formats
216pub mod collection_export;
217pub mod conditions;
218pub mod config;
219/// Cross-protocol consistency engine for unified state across all protocols
220pub mod consistency;
221/// Consumer-driven contracts for tracking usage and detecting consumer-specific breaking changes
222pub mod consumer_contracts;
223/// Contract validation for ensuring API contracts match specifications
224pub mod contract_drift;
225/// Contract validation for ensuring API contracts match specifications
226pub mod contract_validation;
227/// Contract webhooks for notifying external systems about contract changes
228pub mod contract_webhooks;
229pub mod custom_fixture;
230/// Data source abstraction for loading test data from multiple sources
231pub mod data_source;
232/// Deceptive canary mode for routing team traffic to deceptive deploys
233pub mod deceptive_canary;
234/// Docker Compose integration for containerized mock deployments
235pub mod docker_compose;
236/// GitOps integration for drift budget violations
237pub mod drift_gitops;
238pub mod encryption;
239pub mod error;
240pub mod failure_analysis;
241pub mod failure_injection;
242pub mod fidelity;
243pub mod generate_config;
244pub mod generative_schema;
245pub mod git_watch;
246pub mod graph;
247pub mod import;
248pub mod incidents;
249pub mod intelligent_behavior;
250pub mod latency;
251pub mod lifecycle;
252pub mod multi_tenant;
253pub mod network_profiles;
254pub mod openapi;
255pub mod openapi_routes;
256pub mod output_control;
257pub mod overrides;
258pub mod performance;
259/// Pillar metadata system for compile-time pillar tagging
260pub mod pillars;
261pub mod pr_generation;
262pub mod priority_handler;
263pub mod protocol_abstraction;
264pub mod proxy;
265pub mod reality;
266pub mod reality_continuum;
267pub mod record_replay;
268pub mod request_capture;
269pub mod request_chaining;
270pub mod request_fingerprint;
271pub mod request_logger;
272pub mod request_scripting;
273pub mod route_chaos;
274pub mod routing;
275/// Runtime validation for SDKs (request/response validation at runtime)
276pub mod runtime_validation;
277/// Scenario Studio - Visual editor for co-editing business flows
278pub mod scenario_studio;
279pub mod scenarios;
280pub mod schema_diff;
281pub mod security;
282pub mod server_utils;
283/// Time travel and snapshot functionality for saving and restoring system states
284pub mod snapshots;
285pub mod spec_parser;
286pub mod stateful_handler;
287pub mod sync_watcher;
288/// Template library system for shared templates, versioning, and marketplace
289pub mod template_library;
290pub mod templating;
291pub mod time_travel;
292pub mod time_travel_handler;
293pub mod traffic_shaping;
294pub mod validation;
295pub mod verification;
296pub mod voice;
297pub mod workspace;
298pub mod workspace_import;
299pub mod workspace_persistence;
300pub mod ws_proxy;
301
302pub use ab_testing::{
303    apply_variant_to_response, select_variant, ABTestConfig, ABTestReport,
304    ABTestingMiddlewareState, MockVariant, VariantAllocation, VariantAnalytics, VariantComparison,
305    VariantManager, VariantSelectionStrategy,
306};
307pub use behavioral_cloning::{
308    AmplificationScope, BehavioralSequence, EdgeAmplificationConfig, EdgeAmplifier,
309    EndpointProbabilityModel, ErrorPattern, LatencyDistribution, PayloadVariation,
310    ProbabilisticModel, SequenceLearner, SequenceStep,
311};
312pub use chain_execution::{ChainExecutionEngine, ChainExecutionResult, ChainExecutionStatus};
313pub use chaos_utilities::{ChaosConfig, ChaosEngine, ChaosResult, ChaosStatistics};
314pub use conditions::{evaluate_condition, ConditionContext, ConditionError};
315pub use config::{
316    apply_env_overrides, load_config, load_config_with_fallback, save_config, ApiKeyConfig,
317    AuthConfig, ServerConfig,
318};
319pub use consistency::{
320    ConsistencyEngine, EntityState, ProtocolState, SessionInfo, StateChangeEvent, UnifiedState,
321};
322pub use custom_fixture::{CustomFixture, CustomFixtureLoader};
323pub use data_source::{
324    DataSource, DataSourceConfig, DataSourceContent, DataSourceFactory, DataSourceManager,
325    DataSourceType, GitDataSource, HttpDataSource, LocalDataSource,
326};
327pub use deceptive_canary::{
328    CanaryRoutingStrategy, CanaryStats, DeceptiveCanaryConfig, DeceptiveCanaryRouter,
329    TeamIdentifiers,
330};
331pub use error::{Error, Result};
332pub use failure_analysis::{
333    ContributingFactor, FailureContext, FailureContextCollector, FailureNarrative,
334    FailureNarrativeGenerator, NarrativeFrame,
335};
336pub use failure_injection::{
337    create_failure_injector, FailureConfig, FailureInjector, TagFailureConfig,
338};
339pub use fidelity::{FidelityCalculator, FidelityScore, SampleComparator, SchemaComparator};
340pub use generate_config::{
341    discover_config_file, load_generate_config, load_generate_config_with_fallback,
342    save_generate_config, BarrelType, GenerateConfig, GenerateOptions, InputConfig, OutputConfig,
343    PluginConfig,
344};
345pub use git_watch::{GitWatchConfig, GitWatchService};
346pub use graph::{
347    builder::GraphBuilder, relationships, ClusterType, EdgeType, GraphCluster, GraphData,
348    GraphEdge, GraphNode, NodeType, Protocol as GraphProtocol,
349};
350pub use latency::LatencyProfile;
351pub use lifecycle::{
352    LifecycleHook, LifecycleHookRegistry, MockLifecycleEvent, RequestContext, ResponseContext,
353    ServerLifecycleEvent,
354};
355pub use multi_tenant::{
356    MultiTenantConfig, MultiTenantWorkspaceRegistry, RoutingStrategy, TenantWorkspace,
357    WorkspaceContext, WorkspaceRouter, WorkspaceStats,
358};
359pub use network_profiles::{NetworkProfile, NetworkProfileCatalog};
360pub use openapi::{
361    OpenApiOperation, OpenApiRoute, OpenApiSchema, OpenApiSecurityRequirement, OpenApiSpec,
362};
363pub use openapi_routes::{
364    create_registry_from_file, create_registry_from_json, OpenApiRouteRegistry, ValidationOptions,
365};
366pub use output_control::{
367    apply_banner, apply_extension, apply_file_naming_template, build_file_naming_context,
368    process_generated_file, BarrelGenerator, FileNamingContext, GeneratedFile,
369};
370pub use overrides::{OverrideMode, OverrideRule, Overrides, PatchOp};
371pub use pillars::{Pillar, PillarMetadata};
372pub use priority_handler::{
373    MockGenerator, MockResponse, PriorityHttpHandler, PriorityResponse, SimpleMockGenerator,
374};
375pub use protocol_abstraction::{
376    MessagePattern, MiddlewareChain, Protocol, ProtocolMiddleware, ProtocolRequest,
377    ProtocolResponse, RequestMatcher, ResponseStatus, SpecOperation, SpecRegistry,
378    ValidationError as ProtocolValidationError, ValidationResult as ProtocolValidationResult,
379};
380pub use proxy::{ProxyConfig, ProxyHandler, ProxyResponse};
381pub use reality::{PresetMetadata, RealityConfig, RealityEngine, RealityLevel, RealityPreset};
382pub use reality_continuum::{
383    ContinuumConfig, ContinuumRule, MergeStrategy, RealityContinuumEngine, ResponseBlender,
384    TimeSchedule, TransitionCurve, TransitionMode,
385};
386pub use record_replay::{
387    clean_old_fixtures, list_fixtures, list_ready_fixtures, list_smoke_endpoints, RecordHandler,
388    RecordReplayHandler, RecordedRequest, ReplayHandler,
389};
390pub use request_chaining::{
391    ChainConfig, ChainContext, ChainDefinition, ChainExecutionContext, ChainLink, ChainRequest,
392    ChainResponse, ChainStore, ChainTemplatingContext, RequestChainRegistry,
393};
394pub use request_fingerprint::{
395    RequestFingerprint, RequestHandlerResult, ResponsePriority, ResponseSource,
396};
397pub use request_logger::{
398    create_grpc_log_entry, create_http_log_entry, create_websocket_log_entry, get_global_logger,
399    init_global_logger, log_request_global, CentralizedRequestLogger, RequestLogEntry,
400};
401pub use route_chaos::{RouteChaosInjector, RouteFaultResponse, RouteMatcher};
402pub use routing::{HttpMethod, Route, RouteRegistry};
403pub use runtime_validation::{
404    RuntimeValidationError, RuntimeValidationResult, RuntimeValidatorConfig, SchemaMetadata,
405};
406pub use scenario_studio::{
407    ConditionOperator, FlowCondition, FlowConnection, FlowDefinition, FlowExecutionResult,
408    FlowExecutor, FlowPosition, FlowStep, FlowStepResult, FlowType, FlowVariant, StepType,
409};
410pub use scenarios::types::StepResult;
411pub use scenarios::{
412    ScenarioDefinition, ScenarioExecutor, ScenarioParameter, ScenarioRegistry, ScenarioResult,
413    ScenarioStep,
414};
415pub use schema_diff::{to_enhanced_422_json, validation_diff, ValidationError};
416pub use server_utils::errors::{json_error, json_success};
417pub use server_utils::{create_socket_addr, localhost_socket_addr, wildcard_socket_addr};
418pub use snapshots::{SnapshotComponents, SnapshotManager, SnapshotManifest, SnapshotMetadata};
419pub use spec_parser::{GraphQLValidator, OpenApiValidator, SpecFormat};
420pub use stateful_handler::{
421    ResourceIdExtract, StateInfo, StateResponse, StatefulConfig, StatefulResponse,
422    StatefulResponseHandler, TransitionTrigger,
423};
424pub use sync_watcher::{FileChange, SyncEvent, SyncService, SyncWatcher};
425pub use template_library::{
426    TemplateLibrary, TemplateLibraryEntry, TemplateLibraryManager, TemplateMarketplace,
427    TemplateMetadata, TemplateVersion,
428};
429pub use templating::{expand_str, expand_tokens};
430pub use time_travel::{
431    cron::{CronJob, CronJobAction, CronScheduler},
432    get_global_clock, is_time_travel_enabled, now as time_travel_now, register_global_clock,
433    unregister_global_clock, RepeatConfig, ResponseScheduler, ScheduledResponse, TimeScenario,
434    TimeTravelConfig, TimeTravelManager, TimeTravelStatus, VirtualClock,
435};
436pub use time_travel_handler::{
437    time_travel_middleware, ScheduledResponseWrapper, TimeTravelHandler,
438};
439pub use traffic_shaping::{BandwidthConfig, BurstLossConfig, TrafficShaper, TrafficShapingConfig};
440pub use uuid::Uuid;
441pub use validation::{validate_openapi_operation_security, validate_openapi_security, Validator};
442pub use verification::{
443    matches_verification_pattern, verify_at_least, verify_never, verify_requests, verify_sequence,
444    VerificationCount, VerificationRequest, VerificationResult,
445};
446pub use voice::{
447    ConversationContext, ConversationManager, ConversationState, GeneratedWorkspaceScenario,
448    HookTranspiler, ParsedCommand, ParsedWorkspaceScenario, VoiceCommandParser, VoiceSpecGenerator,
449    WorkspaceConfigSummary, WorkspaceScenarioGenerator,
450};
451pub use workspace::{EntityId, Folder, MockRequest, Workspace, WorkspaceConfig, WorkspaceRegistry};
452pub use workspace_import::{
453    create_workspace_from_curl, create_workspace_from_har, create_workspace_from_insomnia,
454    create_workspace_from_postman, import_postman_to_existing_workspace,
455    import_postman_to_workspace, WorkspaceImportConfig, WorkspaceImportResult,
456};
457pub use workspace_persistence::WorkspacePersistence;
458pub use ws_proxy::{WsProxyConfig, WsProxyHandler, WsProxyRule};
459// Note: ValidationError and ValidationResult from spec_parser conflict with schema_diff::ValidationError
460// Use qualified paths: spec_parser::ValidationError, spec_parser::ValidationResult
461
462/// Core configuration for MockForge
463#[derive(Debug, Clone, serde::Deserialize, serde::Serialize)]
464#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
465#[serde(default)]
466pub struct Config {
467    /// Enable latency simulation
468    pub latency_enabled: bool,
469    /// Enable failure simulation
470    pub failures_enabled: bool,
471    /// Enable response overrides
472    pub overrides_enabled: bool,
473    /// Enable traffic shaping (bandwidth + burst loss)
474    pub traffic_shaping_enabled: bool,
475    /// Failure injection configuration
476    pub failure_config: Option<FailureConfig>,
477    /// Proxy configuration
478    pub proxy: Option<ProxyConfig>,
479    /// Default latency profile
480    pub default_latency: LatencyProfile,
481    /// Traffic shaping configuration
482    pub traffic_shaping: TrafficShapingConfig,
483    /// Random chaos configuration
484    pub chaos_random: Option<ChaosConfig>,
485    /// Maximum number of request logs to keep in memory (default: 1000)
486    /// Helps prevent unbounded memory growth from request logging
487    pub max_request_logs: usize,
488    /// Time travel configuration for temporal testing
489    pub time_travel: TimeTravelConfig,
490}
491
492/// Default configuration
493impl Default for Config {
494    fn default() -> Self {
495        Self {
496            latency_enabled: true,
497            failures_enabled: false,
498            overrides_enabled: true,
499            traffic_shaping_enabled: false,
500            failure_config: None,
501            proxy: None,
502            default_latency: LatencyProfile::default(),
503            traffic_shaping: TrafficShapingConfig::default(),
504            chaos_random: None,
505            max_request_logs: 1000, // Default: keep last 1000 requests
506            time_travel: TimeTravelConfig::default(),
507        }
508    }
509}
510
511impl Config {
512    /// Create a ChaosEngine from the chaos_random configuration if enabled
513    pub fn create_chaos_engine(&self) -> Option<ChaosEngine> {
514        self.chaos_random.as_ref().map(|config| ChaosEngine::new(config.clone()))
515    }
516
517    /// Check if random chaos mode is enabled
518    pub fn is_chaos_random_enabled(&self) -> bool {
519        self.chaos_random.as_ref().map(|c| c.enabled).unwrap_or(false)
520    }
521}
522
523#[cfg(test)]
524mod tests {
525    use super::*;
526
527    #[test]
528    fn test_config_default() {
529        let config = Config::default();
530        assert!(config.latency_enabled);
531        assert!(!config.failures_enabled);
532        assert!(config.overrides_enabled);
533        assert!(!config.traffic_shaping_enabled);
534        assert!(config.failure_config.is_none());
535        assert!(config.proxy.is_none());
536    }
537
538    #[test]
539    fn test_config_serialization() {
540        let config = Config::default();
541        let json = serde_json::to_string(&config).unwrap();
542        assert!(json.contains("latency_enabled"));
543        assert!(json.contains("failures_enabled"));
544    }
545
546    #[test]
547    fn test_config_deserialization() {
548        // Use default config and modify
549        let config = Config {
550            latency_enabled: false,
551            failures_enabled: true,
552            ..Default::default()
553        };
554
555        // Serialize and deserialize
556        let json = serde_json::to_string(&config).unwrap();
557        let deserialized: Config = serde_json::from_str(&json).unwrap();
558
559        assert!(!deserialized.latency_enabled);
560        assert!(deserialized.failures_enabled);
561        assert!(deserialized.overrides_enabled);
562    }
563
564    #[test]
565    fn test_config_with_custom_values() {
566        let config = Config {
567            latency_enabled: false,
568            failures_enabled: true,
569            ..Default::default()
570        };
571
572        assert!(!config.latency_enabled);
573        assert!(config.failures_enabled);
574    }
575}
mockforge_core/lib.rs

mockforge_core/
lib.rs
