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 ai_contract_diff;
205pub mod ai_response;
206pub mod cache;
207pub mod chain_execution;
208pub mod chaos_utilities;
209pub mod codegen;
210/// Collection export utilities for exporting mock data in various formats
211pub mod collection_export;
212pub mod conditions;
213pub mod config;
214/// Contract validation for ensuring API contracts match specifications
215pub mod contract_validation;
216/// Contract webhooks for notifying external systems about contract changes
217pub mod contract_webhooks;
218/// Data source abstraction for loading test data from multiple sources
219pub mod data_source;
220/// Docker Compose integration for containerized mock deployments
221pub mod docker_compose;
222pub mod encryption;
223pub mod error;
224pub mod failure_injection;
225pub mod generate_config;
226pub mod generative_schema;
227pub mod git_watch;
228pub mod graph;
229pub mod import;
230pub mod intelligent_behavior;
231pub mod latency;
232pub mod lifecycle;
233pub mod multi_tenant;
234pub mod network_profiles;
235pub mod openapi;
236pub mod openapi_routes;
237pub mod output_control;
238pub mod overrides;
239pub mod performance;
240pub mod priority_handler;
241pub mod protocol_abstraction;
242pub mod proxy;
243pub mod reality;
244pub mod reality_continuum;
245pub mod custom_fixture;
246pub mod record_replay;
247pub mod request_capture;
248pub mod request_chaining;
249pub mod request_fingerprint;
250pub mod request_logger;
251pub mod request_scripting;
252pub mod route_chaos;
253pub mod routing;
254pub mod security;
255pub mod schema_diff;
256pub mod server_utils;
257pub mod spec_parser;
258pub mod stateful_handler;
259pub mod sync_watcher;
260/// Template library system for shared templates, versioning, and marketplace
261pub mod template_library;
262pub mod templating;
263pub mod time_travel;
264pub mod time_travel_handler;
265pub mod traffic_shaping;
266pub mod validation;
267pub mod verification;
268pub mod voice;
269pub mod workspace;
270pub mod workspace_import;
271pub mod workspace_persistence;
272pub mod ws_proxy;
273
274pub use chain_execution::{ChainExecutionEngine, ChainExecutionResult, ChainExecutionStatus};
275pub use chaos_utilities::{ChaosConfig, ChaosEngine, ChaosResult, ChaosStatistics};
276pub use conditions::{evaluate_condition, ConditionContext, ConditionError};
277pub use config::{
278    apply_env_overrides, load_config, load_config_with_fallback, save_config, ApiKeyConfig,
279    AuthConfig, ServerConfig,
280};
281pub use data_source::{
282    DataSource, DataSourceConfig, DataSourceContent, DataSourceFactory, DataSourceManager,
283    DataSourceType, GitDataSource, HttpDataSource, LocalDataSource,
284};
285pub use error::{Error, Result};
286pub use failure_injection::{
287    create_failure_injector, FailureConfig, FailureInjector, TagFailureConfig,
288};
289pub use generate_config::{
290    discover_config_file, load_generate_config, load_generate_config_with_fallback,
291    save_generate_config, BarrelType, GenerateConfig, GenerateOptions, InputConfig, OutputConfig,
292    PluginConfig,
293};
294pub use git_watch::{GitWatchConfig, GitWatchService};
295pub use graph::{
296    builder::GraphBuilder, relationships, ClusterType, EdgeType, GraphCluster, GraphData,
297    GraphEdge, GraphNode, NodeType, Protocol as GraphProtocol,
298};
299pub use latency::LatencyProfile;
300pub use lifecycle::{
301    LifecycleHook, LifecycleHookRegistry, MockLifecycleEvent, RequestContext, ResponseContext,
302    ServerLifecycleEvent,
303};
304pub use multi_tenant::{
305    MultiTenantConfig, MultiTenantWorkspaceRegistry, RoutingStrategy, TenantWorkspace,
306    WorkspaceContext, WorkspaceRouter, WorkspaceStats,
307};
308pub use network_profiles::{NetworkProfile, NetworkProfileCatalog};
309pub use openapi::{
310    OpenApiOperation, OpenApiRoute, OpenApiSchema, OpenApiSecurityRequirement, OpenApiSpec,
311};
312pub use openapi_routes::{
313    create_registry_from_file, create_registry_from_json, OpenApiRouteRegistry, ValidationOptions,
314};
315pub use output_control::{
316    apply_banner, apply_extension, apply_file_naming_template, build_file_naming_context,
317    process_generated_file, BarrelGenerator, FileNamingContext, GeneratedFile,
318};
319pub use overrides::{OverrideMode, OverrideRule, Overrides, PatchOp};
320pub use priority_handler::{
321    MockGenerator, MockResponse, PriorityHttpHandler, PriorityResponse, SimpleMockGenerator,
322};
323pub use protocol_abstraction::{
324    MessagePattern, MiddlewareChain, Protocol, ProtocolMiddleware, ProtocolRequest,
325    ProtocolResponse, RequestMatcher, ResponseStatus, SpecOperation, SpecRegistry,
326    ValidationError as ProtocolValidationError, ValidationResult as ProtocolValidationResult,
327};
328pub use proxy::{ProxyConfig, ProxyHandler, ProxyResponse};
329pub use reality::{PresetMetadata, RealityConfig, RealityEngine, RealityLevel, RealityPreset};
330pub use reality_continuum::{
331    ContinuumConfig, ContinuumRule, MergeStrategy, RealityContinuumEngine, ResponseBlender,
332    TimeSchedule, TransitionCurve, TransitionMode,
333};
334pub use custom_fixture::{CustomFixture, CustomFixtureLoader};
335pub use record_replay::{
336    clean_old_fixtures, list_fixtures, list_ready_fixtures, list_smoke_endpoints, RecordHandler,
337    RecordReplayHandler, RecordedRequest, ReplayHandler,
338};
339pub use request_chaining::{
340    ChainConfig, ChainContext, ChainDefinition, ChainExecutionContext, ChainLink, ChainRequest,
341    ChainResponse, ChainStore, ChainTemplatingContext, RequestChainRegistry,
342};
343pub use request_fingerprint::{
344    RequestFingerprint, RequestHandlerResult, ResponsePriority, ResponseSource,
345};
346pub use request_logger::{
347    create_grpc_log_entry, create_http_log_entry, create_websocket_log_entry, get_global_logger,
348    init_global_logger, log_request_global, CentralizedRequestLogger, RequestLogEntry,
349};
350pub use route_chaos::{RouteChaosInjector, RouteFaultResponse, RouteMatcher};
351pub use routing::{HttpMethod, Route, RouteRegistry};
352pub use schema_diff::{to_enhanced_422_json, validation_diff, ValidationError};
353pub use server_utils::errors::{json_error, json_success};
354pub use server_utils::{create_socket_addr, localhost_socket_addr, wildcard_socket_addr};
355pub use spec_parser::{GraphQLValidator, OpenApiValidator, SpecFormat};
356pub use stateful_handler::{
357    ResourceIdExtract, StateInfo, StateResponse, StatefulConfig, StatefulResponse,
358    StatefulResponseHandler, TransitionTrigger,
359};
360pub use sync_watcher::{FileChange, SyncEvent, SyncService, SyncWatcher};
361pub use template_library::{
362    TemplateLibrary, TemplateLibraryEntry, TemplateLibraryManager, TemplateMarketplace,
363    TemplateMetadata, TemplateVersion,
364};
365pub use templating::{expand_str, expand_tokens};
366pub use time_travel::{
367    cron::{CronJob, CronJobAction, CronScheduler},
368    get_global_clock, is_time_travel_enabled, now as time_travel_now, register_global_clock,
369    unregister_global_clock, RepeatConfig, ResponseScheduler, ScheduledResponse, TimeScenario,
370    TimeTravelConfig, TimeTravelManager, TimeTravelStatus, VirtualClock,
371};
372pub use time_travel_handler::{
373    time_travel_middleware, ScheduledResponseWrapper, TimeTravelHandler,
374};
375pub use traffic_shaping::{BandwidthConfig, BurstLossConfig, TrafficShaper, TrafficShapingConfig};
376pub use uuid::Uuid;
377pub use validation::{validate_openapi_operation_security, validate_openapi_security, Validator};
378pub use verification::{
379    matches_verification_pattern, verify_at_least, verify_never, verify_requests, verify_sequence,
380    VerificationCount, VerificationRequest, VerificationResult,
381};
382pub use voice::{
383    ConversationContext, ConversationManager, ConversationState, ParsedCommand, VoiceCommandParser,
384    VoiceSpecGenerator,
385};
386pub use workspace::{EntityId, Folder, MockRequest, Workspace, WorkspaceConfig, WorkspaceRegistry};
387pub use workspace_import::{
388    create_workspace_from_curl, create_workspace_from_har, create_workspace_from_insomnia,
389    create_workspace_from_postman, import_postman_to_existing_workspace,
390    import_postman_to_workspace, WorkspaceImportConfig, WorkspaceImportResult,
391};
392pub use workspace_persistence::WorkspacePersistence;
393pub use ws_proxy::{WsProxyConfig, WsProxyHandler, WsProxyRule};
394// Note: ValidationError and ValidationResult from spec_parser conflict with schema_diff::ValidationError
395// Use qualified paths: spec_parser::ValidationError, spec_parser::ValidationResult
396
397/// Core configuration for MockForge
398#[derive(Debug, Clone, serde::Deserialize, serde::Serialize)]
399#[serde(default)]
400pub struct Config {
401    /// Enable latency simulation
402    pub latency_enabled: bool,
403    /// Enable failure simulation
404    pub failures_enabled: bool,
405    /// Enable response overrides
406    pub overrides_enabled: bool,
407    /// Enable traffic shaping (bandwidth + burst loss)
408    pub traffic_shaping_enabled: bool,
409    /// Failure injection configuration
410    pub failure_config: Option<FailureConfig>,
411    /// Proxy configuration
412    pub proxy: Option<ProxyConfig>,
413    /// Default latency profile
414    pub default_latency: LatencyProfile,
415    /// Traffic shaping configuration
416    pub traffic_shaping: TrafficShapingConfig,
417    /// Random chaos configuration
418    pub chaos_random: Option<ChaosConfig>,
419    /// Maximum number of request logs to keep in memory (default: 1000)
420    /// Helps prevent unbounded memory growth from request logging
421    pub max_request_logs: usize,
422    /// Time travel configuration for temporal testing
423    pub time_travel: TimeTravelConfig,
424}
425
426/// Default configuration
427impl Default for Config {
428    fn default() -> Self {
429        Self {
430            latency_enabled: true,
431            failures_enabled: false,
432            overrides_enabled: true,
433            traffic_shaping_enabled: false,
434            failure_config: None,
435            proxy: None,
436            default_latency: LatencyProfile::default(),
437            traffic_shaping: TrafficShapingConfig::default(),
438            chaos_random: None,
439            max_request_logs: 1000, // Default: keep last 1000 requests
440            time_travel: TimeTravelConfig::default(),
441        }
442    }
443}
444
445impl Config {
446    /// Create a ChaosEngine from the chaos_random configuration if enabled
447    pub fn create_chaos_engine(&self) -> Option<ChaosEngine> {
448        self.chaos_random.as_ref().map(|config| ChaosEngine::new(config.clone()))
449    }
450
451    /// Check if random chaos mode is enabled
452    pub fn is_chaos_random_enabled(&self) -> bool {
453        self.chaos_random.as_ref().map(|c| c.enabled).unwrap_or(false)
454    }
455}
456
457#[cfg(test)]
458mod tests {
459    use super::*;
460
461    #[test]
462    fn test_config_default() {
463        let config = Config::default();
464        assert!(config.latency_enabled);
465        assert!(!config.failures_enabled);
466        assert!(config.overrides_enabled);
467        assert!(!config.traffic_shaping_enabled);
468        assert!(config.failure_config.is_none());
469        assert!(config.proxy.is_none());
470    }
471
472    #[test]
473    fn test_config_serialization() {
474        let config = Config::default();
475        let json = serde_json::to_string(&config).unwrap();
476        assert!(json.contains("latency_enabled"));
477        assert!(json.contains("failures_enabled"));
478    }
479
480    #[test]
481    fn test_config_deserialization() {
482        // Use default config and modify
483        let config = Config {
484            latency_enabled: false,
485            failures_enabled: true,
486            ..Default::default()
487        };
488
489        // Serialize and deserialize
490        let json = serde_json::to_string(&config).unwrap();
491        let deserialized: Config = serde_json::from_str(&json).unwrap();
492
493        assert!(!deserialized.latency_enabled);
494        assert!(deserialized.failures_enabled);
495        assert!(deserialized.overrides_enabled);
496    }
497
498    #[test]
499    fn test_config_with_custom_values() {
500        let config = Config {
501            latency_enabled: false,
502            failures_enabled: true,
503            ..Default::default()
504        };
505
506        assert!(!config.latency_enabled);
507        assert!(config.failures_enabled);
508    }
509}
mockforge_core/lib.rs

mockforge_core/
lib.rs
